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.

Features

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, two channels: a project's style guide (add_project_source) carries the RULES that hold across a set — polycount budgets, naming, real-world sizes — and applies to every generation in the project without being retyped. A style_reference_submission_id carries the LOOK: point at a finished model and the next one matches its palette, materials and finish. Text states constraints well and a picture shows appearance well; they combine rather than substitute. Reusing a reference_image_id is also free.

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 — see below.

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.

Sign In

uvx thrixel-mcp@latest login

It prints a link and a short code, and opens the link if you have a browser:

  Open this link to finish signing in:
      https://thrixel.com/create/cli-auth?code=WXYZ-4821

  Confirm the page shows this code:  WXYZ-4821

  Waiting for approval...

Open the link, check that the code on the page matches the one in your terminal, and click Approve. Sign-up happens on that page if you do not have an account yet. The command then stores a key in ~/.thrixel/credentials.json (mode 0600). Nothing is copied by hand, and the key never enters the agent's conversation.

The key does not expire, so this is a one-time step. thrixel-mcp status shows what is stored; thrixel-mcp logout removes it.

Works over SSH and inside containers: with no browser available it simply prints the link, and you can open it on any machine.

Installation

Option 1 · Claude Code · Recommended

After signing in above, no key goes in the command:

claude mcp add --scope user thrixel -- uvx thrixel-mcp@latest

--scope user is the part that matters. claude mcp add defaults to --scope local, which registers the server for the current directory only - so every new project starts with no Thrixel tools, and you add it and restart again. User scope registers it once for every project on the machine. Use --scope project instead only when you want the server recorded in a .mcp.json your teammates will share.

The server reads ~/.thrixel/credentials.json, written by login above. That is the recommended path, and not only for convenience: the key goes straight from the sign-in into a 0600 file, so it never appears on a command line, in your shell history, or in any config file.

claude mcp add --scope user thrixel --env THRIXEL_API_KEY=sk-thrixel-YOUR_API_KEY -- uvx thrixel-mcp@latest

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

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

claude mcp add-json --scope user thrixel "{""command"":""uvx"",""args"":[""thrixel-mcp@latest""],""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@latest
Use this env var: THRIXEL_API_KEY=sk-thrixel-YOUR_API_KEY

Option 3 · Manual Install

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

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

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

pip install thrixel-mcp

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

# 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

Activate After Install

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

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.

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 --scope user thrixel --env THRIXEL_API_KEY=... -- uvx thrixel-mcp@latest. 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. Generate a fresh one at thrixel.com/create/#settings/api-keys → Create new secret key, then update the env block.
• 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. Run large batches in waves; thrixel_account_status shows your cap and what is in flight, and thrixel_pricing lists the cap for every plan.
• "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 — check what you have with uvx thrixel-mcp@latest --version, and compare it against what your client loaded (/mcp in Claude Code shows the running server's version). The configs above all say thrixel-mcp@latest, so a new session picks up new releases on its own; if yours says plain thrixel-mcp, add @latest. Note that an MCP client starts its servers once, at session start — updating the package cannot change a server that is already running, so restart the client after an update. To clear the cache outright: uvx --refresh thrixel-mcp@latest --version.

Costs

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

The reference image is billed separately. Given only a prompt, those three operations have to generate the reference image the job runs on, and that generation is charged on its own — about 7 cubes, so the call totals roughly 47 rather than 40. Supplying the image yourself, or reusing one with reference_image_id, skips the generation and costs the flat 40. The live figure is on GET /api/v1/tiers as ref_image_cubes; thrixel_pricing reports it.

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

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

# uv
uv sync

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

Run the server the way a client does, against a local backend:

THRIXEL_API_BASE=http://localhost:8000 THRIXEL_API_KEY=sk-thrixel-... \
  uvx --from . thrixel-mcp

To see the raw protocol, point the MCP Inspector at it - -e flags go after the target command:

npx -y @modelcontextprotocol/inspector --cli uvx thrixel-mcp \
  --method tools/list -e THRIXEL_API_KEY=sk-thrixel-...

Drop --cli for a web UI that shows each request/response pair. Claude Code's claude --debug-file /tmp/mcp.log -p "..." logs the connection, negotiated capabilities and dispatched tools, though not the JSON-RPC payloads.

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. It speaks stdio, which is what every MCP client above launches it as.

License

MIT