thrixel-mcp 0.1.0

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.
• 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:

  curl -LsSf https://astral.sh/uv/install.sh | sh      # macOS / Linux
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
  

• 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

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

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):

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

Windows: if uvx is not on PATH for GUI apps, use the absolute path, e.g. "command": "C:\\Users\\you\\.local\\bin\\uvx.exe".

Claude Desktop

Add to claude_desktop_config.json:

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

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 — SSH, works while the repo is private (needs repo access)
uvx --from git+ssh://[e-mail]/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+ssh://[e-mail]/thrixel/thrixel_mcp", "thrixel-mcp"].

The git+https:// form only works once the repository is public; until then uvx cannot authenticate and fails with could not read Username.

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

• spawn uvx ENOENT — the client cannot find uvx on PATH. Use the absolute path (which uvx, or %USERPROFILE%\.local\bin\uvx.exe on Windows).
• 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" — detail, sculpt and texture cost 40 cubes each. 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.

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