Blender MCP Router
FastMCP server that exposes two layers of functionality:
- LLM routing through LiteLLM so a single FastMCP tool can reach OpenAI, Anthropic, xAI, or any other LiteLLM-supported provider.
- Blender bridge that proxies to the Blender MCP add-on over a persistent TCP socket, providing scene inspection, PolyHaven / Sketchfab helpers, and Hyper3D automation.
The server is designed for FastMCP Hub distribution: pyproject.toml defines the package, the MCP endpoint is hosted via FastMCP, and an optional REST shim is exposed for the Blender add-on.
Requirements
- Python 3.10+
- Blender MCP add-on running locally (for the Blender tools)
- API keys for any LLM providers you plan to route through LiteLLM
Install dependencies via:
pip install -e .
Configuration
Copy .env.example to .env and fill in the values.
| Variable | Purpose |
|---|---|
OPENAI_API_KEY | Used by LiteLLM when routing to OpenAI models |
XAI_API_KEY | Used for xAI (Grok) requests via LiteLLM |
ANTHROPIC_API_KEY | Used for Anthropics models via LiteLLM |
OPENAI_MODEL | Optional override for the gpt-5 alias |
XAI_MODEL | Optional override for the grok-4-fast alias |
ANTHROPIC_MODEL | Optional override for the claude-4 alias |
MCP_REST_TOKEN | Shared secret for REST shim (X-Token header) |
All LLM-specific environment variables supported by LiteLLM can be passed through here as well (see LiteLLM docs for provider-specific keys).
Running
After configuration, start the server via the script entry point:
blender-mcp-router
The process starts two services:
- FastMCP HTTP endpoint on
127.0.0.1:8974/mcp - REST bridge for the Blender add-on on
127.0.0.1:8975
Both services are started inside server.main() so FastMCP Hub (or pipx run blender-mcp-router) can launch them.
MCP Tools
server.py registers the following FastMCP tools:
generate_text: Unified text generation routed through LiteLLM- Blender tools:
get_scene_info,get_object_info,get_viewport_screenshot,execute_blender_code, PolyHaven/Sketchfab helpers, and Hyper3D automation helpers
Each Blender tool forwards to the Blender MCP add-on using a JSON-over-TCP API. See that add-on for port configuration (default localhost:9876).
REST Shim /tools/call
The REST API exposes a subset of the MCP tools so non-MCP clients (like the Blender add-on) can call them. Requests must include an X-Token header if MCP_REST_TOKEN is set. The response format mirrors MCP content objects (text, json, image).
Health Check
GET /health returns { "ok": true } so deployment targets can monitor the process.
Development
- Run linting/formatting as desired (none enforced yet).
- The LiteLLM dependency keeps provider selection abstract; add more aliases in
MODEL_MAPas needed. - Additional tools can be exposed by adding
@mcp.tool()functions and listing them in_HTTP_EXPOSED_TOOL_NAMESwhen required by the REST shim.