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

Building a game? The Build World plugin installs this server for you, together with a skill that turns one prompt into a playable Unity or Three.js game. Two commands on Claude Code or Codex, and there is nothing below to do. The rest of this section is for wiring the server in on its own.

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. A job still running when the wait ends is not an error: it keeps running (and is charged when it completes), and thrixel_job_status picks it up. Raise THRIXEL_TIMEOUT_S to wait longer, or submit with wait=false and poll.
• "Could not verify the HTTPS certificate": an antivirus web shield or corporate proxy is intercepting HTTPS. The server trusts certificates installed in the operating system's store, so allow api.thrixel.com in that product or install its root certificate system-wide.
• 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 a detail pass totals roughly 21 rather than 14. Supplying the image yourself, or reusing one with reference_image_id, skips the generation and costs the flat price. 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