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:

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.

Related MCP server: Blender MCP Server

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

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

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" }
    }
  }
}

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.

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

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.

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:

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:

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

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.

Seeing the raw protocol

Three levels of visibility, least to most invasive.

1. Tool schemas and one-off calls — MCP Inspector. Prints the raw JSON-RPC result. Note that -e flags go after the target command:

# every tool exactly as the model receives it
npx -y @modelcontextprotocol/inspector --cli uvx thrixel-mcp \
  --method tools/list -e THRIXEL_API_KEY=sk-thrixel-...

# invoke one
npx -y @modelcontextprotocol/inspector --cli uvx thrixel-mcp \
  --method tools/call --tool-name thrixel_account_status \
  -e THRIXEL_API_KEY=sk-thrixel-...

Drop --cli for a web UI that shows each request/response pair.

2. Client-side lifecycle — Claude Code debug log. Shows the connection, negotiated capabilities, which tool was dispatched, and the server's stderr. It does not include the JSON-RPC payloads:

claude --debug-file /tmp/mcp.log -p "check my thrixel account"
grep -i mcp /tmp/mcp.log

3. Every frame from a real session — the wire tap. A transparent stdio proxy that logs both directions to JSONL. This is the only way to see what the model actually chose to send during a normal session:

claude mcp add thrixel-tapped \
  --env THRIXEL_API_KEY=sk-thrixel-... \
  --env MCP_WIRETAP_LOG=/tmp/thrixel-wire.jsonl \
  -- python /path/to/thrixel_mcp/tests/wiretap.py uvx thrixel-mcp

tail -f /tmp/thrixel-wire.jsonl | jq -c '{dir, method, tool, id}'

Each line carries dir (client->server / server->client), the parsed msg, and lifted method / tool / id fields for grepping.

HTTP Transport

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

License

MIT