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

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

Get an API Key

1. Open thrixel.com/beta/#settings/api-keys (sign in first if prompted).

2. Click Create new secret key.

3. Copy the key. It starts with sk-thrixel- and is shown only once — once the dialog closes you cannot read it again, only revoke it and make another.

Keep the key in the env block of your MCP client config (below). It never enters the agent's conversation, so the agent cannot leak or misuse it.

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:

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 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. Generate a fresh one at thrixel.com/beta/#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 (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

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