thrixel-mcp 0.1.1

MCP server for Thrixel — text/image to editable, game-ready 3D assets.

Thrixel MCP Server

Model Context Protocol (MCP) server for the Thrixel 3D generation platform. Enables AI agents to create, edit, detail, and download game-ready 3D models through natural conversation — and to see each result before building on it.

TODO — demo GIF goes here (docs/demo.gif).

Features

12 tools covering the Thrixel generation pipeline:

Category	Tools
Create	thrixel_create_model, thrixel_sculpt_model
Refine	thrixel_edit_model, thrixel_autofix_model
Detail & Texture	thrixel_detail_model, thrixel_retexture_model
Optimize	thrixel_reduce_triangles
Inspect	thrixel_inspect_model, thrixel_list_assets
Jobs & Download	thrixel_job_status, thrixel_download
Account	thrixel_account_status

Key Capabilities

• Text to 3D: create_model returns an editable, multi-part mesh — parts stay separate and named, so you can retexture or transform individual pieces later. The default for props, vehicles, buildings, weapons, furniture.
• Image to 3D: sculpt_model turns a photo or a description into a dense single organic mesh — creatures, characters, plants, food.
• Natural-language editing: edit_model changes one thing and leaves the rest alone, optionally scoped to named parts. Iterating beats regenerating.
• Detail & retexture: detail_model adds high-resolution geometry and PBR texture; retexture_model swaps materials without touching geometry — the cheap way to restyle a whole asset set.
• Free triangle reduction: reduce_triangles hits a game budget for zero cubes and routes to the right backend operation automatically. Never re-run a detail pass just to get a lighter mesh.
• Budget-aware: account_status reports the cube balance, the enforced concurrency cap, and what is running, so a batch can be sized before it starts instead of failing partway through.
• Visual feedback loop: every finished job returns a rendered thumbnail as image content, so the agent can judge the result and retry rather than carrying a broken asset forward.
• Waits for you: job tools block until the model is finished and write the GLB straight into your project. One tool call equals one finished asset — no agent-authored polling loop to silently give up halfway.
• Style consistency: reuse one reference_image_id across many assets, or pass style_reference_submission_id, to keep a set looking like a set. Reusing a reference image is not re-charged.

Prerequisites

• uv — one binary, no Python setup needed.

  macOS / Linux

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  Windows (PowerShell)

  irm https://astral.sh/uv/install.ps1 | iex
  

• A Thrixel API key (get one here — Account → API keys)

uvx fetches the server and a suitable Python into a throwaway environment on first run. You do not need to clone anything, create a virtualenv, or install Python yourself.

Installation

Option 1 · Claude Code · Recommended

This form takes no JSON, so it works identically in every shell — use it on Windows and macOS / Linux alike:

claude mcp add thrixel --env THRIXEL_API_KEY=sk-thrixel-YOUR_API_KEY -- uvx thrixel-mcp

Prefer add-json? Quoting differs per shell

Only the outer quoting changes; the JSON itself is identical.

macOS / Linux, Git Bash, WSL

claude mcp add-json thrixel '{"command":"uvx","args":["thrixel-mcp"],"env":{"THRIXEL_API_KEY":"sk-thrixel-YOUR_API_KEY"}}'

Windows PowerShell — PowerShell rewrites inner double quotes when passing arguments to a native command, so they must be escaped. Without this you get Invalid configuration: : Invalid input.

claude mcp add-json thrixel '{\"command\":\"uvx\",\"args\":[\"thrixel-mcp\"],\"env\":{\"THRIXEL_API_KEY\":\"sk-thrixel-YOUR_API_KEY\"}}'

Windows CMD — wrap in double quotes and double every inner one.

claude mcp add-json thrixel "{""command"":""uvx"",""args"":[""thrixel-mcp""],""env"":{""THRIXEL_API_KEY"":""sk-thrixel-YOUR_API_KEY""}}"

Verify with claude mcp list, then open a new session.

Option 2 · Install by Asking Your AI Agent

Already chatting with Cursor / Claude Code / Codex? Paste this prompt:

Install the Thrixel MCP server for me. Docs: https://github.com/thrixel/thrixel_mcp
Run it with: uvx thrixel-mcp
Use this env var: THRIXEL_API_KEY=sk-thrixel-YOUR_API_KEY

Option 3 · Manual Install

Cursor

Paste into .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

macOS / Linux

{
  "mcpServers": {
    "thrixel": {
      "command": "uvx",
      "args": ["thrixel-mcp"],
      "env": { "THRIXEL_API_KEY": "sk-thrixel-YOUR_API_KEY" }
    }
  }
}

Windows — GUI apps often do not inherit your shell PATH, so give the full path to uvx.exe (find it with where.exe uvx):

{
  "mcpServers": {
    "thrixel": {
      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
      "args": ["thrixel-mcp"],
      "env": { "THRIXEL_API_KEY": "sk-thrixel-YOUR_API_KEY" }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thrixel": {
      "command": "uvx",
      "args": ["thrixel-mcp"],
      "env": { "THRIXEL_API_KEY": "sk-thrixel-YOUR_API_KEY" }
    }
  }
}

Windows: replace "uvx" with the absolute path to uvx.exe — the desktop app does not inherit your shell PATH. See the Cursor block above.

Codex / VS Code / Windsurf

Same shape as above — command: "uvx", args: ["thrixel-mcp"], and THRIXEL_API_KEY in the env block.

Without uv (pip fallback)

pip install thrixel-mcp

Then point the client at your interpreter:

{
  "mcpServers": {
    "thrixel": {
      "command": "python",
      "args": ["-m", "thrixel_mcp.server"],
      "env": { "THRIXEL_API_KEY": "sk-thrixel-YOUR_API_KEY" }
    }
  }
}

Use an absolute path to python if the client cannot find it on PATH.

Pre-release / unpublished builds

uvx can run straight from the repository, no PyPI release needed:

# latest main, ahead of the newest release
uvx --from git+https://github.com/thrixel/thrixel_mcp thrixel-mcp

# a local checkout
uvx --from /path/to/thrixel_mcp thrixel-mcp

Same shape in a client config — replace args with ["--from", "git+https://github.com/thrixel/thrixel_mcp", "thrixel-mcp"].

Activate After Install

Most clients auto-load the new server, but Cursor and VS Code require a manual toggle:

Client	What to do	Verify
Claude Code	Nothing — auto-loads on next message	/mcp shows thrixel ✓ connected
Cursor	Restart → Settings → MCP & Integrations → toggle thrixel on → wait for green dot ● → open a new chat	List the thrixel tools available
Claude Desktop	Quit & relaunch the app	List the thrixel tools available
VS Code	Run command MCP: List Servers → click thrixel → Start	List the thrixel tools available
Codex	Nothing — auto-loads on next session	List the thrixel tools available

TODO — connected-state screenshot goes here (docs/connected.png).

Usage

Once connected, just ask:

Make me a low-poly wooden market stall for a game, under 5000 triangles.

The agent will chain thrixel_create_model → thrixel_detail_model → thrixel_reduce_triangles, save the GLB into ./thrixel_assets/, and show you the render at each step.

TODO — pipeline before/after image goes here (docs/pipeline.png).

Troubleshooting

• Invalid configuration: : Invalid input (Windows) — claude mcp add-json received mangled JSON because PowerShell rewrote the inner double quotes. Either escape them (\") or skip JSON entirely and use the flag form: claude mcp add thrixel --env THRIXEL_API_KEY=... -- uvx thrixel-mcp. See Option 1.
• spawn uvx ENOENT — the client cannot find uvx on PATH. Use the absolute path: which uvx on macOS / Linux, where.exe uvx on Windows (usually C:\Users\YOU\.local\bin\uvx.exe). GUI clients are the usual culprits — they don't inherit your shell PATH.
• THRIXEL_API_KEY is not set — the key didn't reach the server. Make sure it sits inside an "env": {...} block in your MCP config, not in args.
• Tool calls return "Thrixel rejected the API key" — the key is invalid or revoked. Regenerate at https://thrixel.com/beta (Account → API keys).
• First call is slow — uvx is resolving and caching the package. Subsequent starts are fast.
• "You have N jobs already running" — you hit the per-plan concurrency cap (free 2, pro 5, studio 10). Run large batches in waves; thrixel_account_status shows what's in flight.
• "Out of cubes" — see Costs. thrixel_account_status shows the balance; thrixel_reduce_triangles and rebakes are free.
• Jobs time out — GPU work can queue behind other jobs. Raise THRIXEL_TIMEOUT_S, or submit with wait=false and poll via thrixel_job_status.
• Client doesn't list thrixel — make sure the config file is valid JSON (no trailing commas), then fully restart the client.
• Stuck on an old version — uvx caches builds. Force a refresh with uvx --refresh thrixel-mcp.

Costs

Cubes are Thrixel's usage credits. Three pricing shapes:

Operation	Cost
detail_model, sculpt_model, retexture_model	Flat 40 cubes each
reduce_triangles, texture rebake	Free
create_model, edit_model, autofix_model	Metered — charged after the run on actual model usage

Metered is not a synonym for cheap. It scales with how complex the request is: observed runs land anywhere from single digits to over 100 cubes, so a complex create_model can cost more than a flat GPU operation. Call thrixel_account_status to see your balance before a big batch.

Every export format (GLB, FBX, OBJ, STL, USDZ) is free on every plan.

Configuration

Environment Variable	Description	Default
THRIXEL_API_KEY	Required. Your Thrixel API key (starts with sk-thrixel-)	—
THRIXEL_API_BASE	API base URL	https://api.thrixel.com
THRIXEL_OUTPUT_DIR	Where generated models are written. Writes outside it are refused	./thrixel_assets
THRIXEL_TIMEOUT_S	Ceiling in seconds for a single submit-and-wait cycle	600
THRIXEL_LOG_LEVEL	Server log level, written to stderr	INFO

Development

End users need only uvx; contributors want a real environment. Either works:

git clone https://github.com/thrixel/thrixel_mcp.git
cd thrixel_mcp

# uv
uv sync --extra dev

# or conda
conda env create -f environment.yml
conda activate thrixel-mcp

# Unit tests — no backend required
pytest

# End-to-end against a local backend
export THRIXEL_API_BASE=http://localhost:8000
export THRIXEL_API_KEY=sk-thrixel-...

python tests/smoke_local.py                       # list registered tools
python tests/smoke_local.py thrixel_account_status
python tests/smoke_local.py thrixel_create_model '{"prompt":"a rusted oil drum"}'

Run the packaged entry point exactly as a user would:

uvx --from . thrixel-mcp

This server holds no state and no business logic — it is a client of the public Thrixel API. Anything it can do, a direct API caller can do too.

HTTP Transport

TODO — remote HTTP transport is planned but not implemented. stdio only for now.

License

MIT