Content
# blender-mcp-suite
**Modular MCP server for Blender** — control Blender from Claude, Cursor, VS Code or any MCP client with 61 tools across 9 lazy-loaded categories, deterministic ground-truth verification, and PolyHaven asset integration.
Built by combining the best ideas from the Blender MCP ecosystem into one coherent, tested suite (see [Prior art](#prior-art--acknowledgements)).
## Highlights
- **Lazy-loaded tool categories** — the LLM sees only 15 core tools at startup; it enables `mesh_edit`, `materials`, `animation`, `geometry_nodes`, `render`, `polyhaven`, ... on demand via `enable_tools`. Keeps the model's context small without sacrificing power. `--eager` flag registers everything upfront for clients without `tools/list_changed` support.
- **Ground-truth verification** — `scene_measure` (distances, surface gaps, bounding boxes, mesh stats) and `scene_assert` (transforms, materials, modifiers, bounds) let the model *verify* its work deterministically instead of guessing from renders.
- **Viewport screenshots & renders returned as images** — the model sees the scene; headless Blender gets a fast Workbench-render fallback.
- **Thread-safe by construction** — the addon's socket threads never touch `bpy`; every command is dispatched to Blender's main thread through a queue drained by `bpy.app.timers`, with timeouts that can't crash Blender.
- **Reliable wire protocol** — length-prefixed JSON frames over TCP handle megabyte-scale image payloads deterministically, with automatic reconnection.
- **PolyHaven integration** — search and download free CC0 HDRIs (auto world setup), PBR texture sets (auto material wiring) and models (auto import). No API key. Downloads run in the server process, not inside Blender.
- **Portmanteau tools** — one tool covers a family of operations via an `op`/`type` parameter, so 61 tools cover a surface that would otherwise take 150+.
## Requirements
- Blender **4.2+** (tested on 4.5 LTS)
- Python **3.10+**
## Installation
### 1. Install the Python package
```bash
pip install git+https://github.com/iQreu/blender-mcp-suite.git
# or from a clone:
git clone https://github.com/iQreu/blender-mcp-suite.git
cd blender-mcp-suite
pip install .
```
### 2. Install the Blender addon
Download `blender_mcp_suite_addon.zip` from [Releases](https://github.com/iQreu/blender-mcp-suite/releases) (or build it with `python scripts/build_addon.py`), then in Blender:
**Edit → Preferences → Add-ons → Install from Disk…** → select the zip → enable **Blender MCP Suite**.
Or headless: `python scripts/install_addon.py`
### 3. Start the bridge
In Blender's 3D viewport press `N` → **MCP** tab → **Start Server** (default port 9876).
### 4. Configure your MCP client
Claude Desktop / Claude Code (`claude mcp add blender -- python -m blender_mcp_suite`) or JSON config:
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["-m", "blender_mcp_suite"]
}
}
}
```
For clients that don't support dynamic tool-list updates (some VS Code builds), add `"--eager"` to `args`.
Environment variables: `BLENDER_MCP_HOST`, `BLENDER_MCP_PORT`, `BLENDER_MCP_EAGER`, `BLENDER_MCP_DISABLE_EXECUTE_CODE`, `BLENDER_MCP_TIMEOUT`, `BLENDER_MCP_DOWNLOAD_DIR`.
## Tool catalog
### Core (always loaded, 15)
| Tool | Purpose |
|---|---|
| `ping_blender` | health check, versions |
| `scene_info` | overview / objects / hierarchy / stats |
| `object_inspect` | full detail for one object |
| `object_create` | cube, sphere, cylinder, plane, cone, torus, empty, text, curve |
| `object_modify` | transform / rename / parent / visibility / origin (batched) |
| `object_delete`, `object_duplicate`, `select_objects` | object management |
| `viewport_screenshot` | see the scene (headless fallback: fast render) |
| `scene_measure` | distance, surface gap, bounding box, dimensions, vert/face counts |
| `scene_assert` | object_exists, count_equals, transform_near, inside_bounds, has_material, has_modifier |
| `history` | undo checkpoint / undo / redo |
| `execute_code` | arbitrary Python escape hatch (disableable) |
| `enable_tools`, `list_tool_categories` | lazy loading control |
### Lazy categories (46 tools)
| Category | Tools |
|---|---|
| `mesh_edit` (8) | select elements, extrude, inset/bevel, subdivide/loopcut, transform selection, merge/weld, boolean, cleanup |
| `materials` (7) | Principled BSDF create, assign, inspect, shader node add/connect/set, one-call PBR texture setup |
| `modifiers` (4) | add, edit, apply/remove, list |
| `animation` (6) | keyframes, multi-keyframe transform helper, timeline, f-curve easing, animated-state preview, constraints |
| `geometry_nodes` (5) | groups, node add/connect, modifier inputs, templates (scatter, array, curve-to-mesh) |
| `render` (4) | settings, still render (returned as image), animation render, inspect |
| `lighting_camera` (5) | lights, cameras, auto-frame objects, world color/HDRI, depth of field |
| `import_export` (3) | import (obj/fbx/gltf/stl/usd/ply), export, append from .blend |
| `polyhaven` (4) | search, HDRI download (auto world), texture download (auto material), model download (auto import) |
## Example session
> "Enable materials and lighting tools, build a small scene with a shiny red torus on a plane, light it with an HDRI from PolyHaven, and show me the result."
The model calls `enable_tools(["materials", "lighting_camera", "polyhaven"])`, creates objects, verifies placement with `scene_measure`, downloads an HDRI, frames the camera with `camera_frame_objects`, and returns a `render_image` — all with ground truth checks along the way.
## Development
```bash
pip install -e .[dev]
pytest # unit tests (no Blender needed)
pytest -m e2e # end-to-end against real headless Blender
python scripts/dev_link_addon.py # junction the addon into Blender's addons dir
```
Architecture:
```
MCP client ↔ stdio ↔ blender-mcp-suite (FastMCP) ↔ TCP 127.0.0.1:9876
(4-byte length-prefixed JSON) ↔ addon socket thread ↔ queue + bpy.app.timers ↔ bpy (main thread)
```
## Prior art / acknowledgements
This project reimplements (clean-room) and combines ideas pioneered by:
- [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) (MIT) — the addon + TCP socket architecture and PolyHaven integration
- [PatrykIti/blender-ai-mcp](https://github.com/PatrykIti/blender-ai-mcp) (Apache 2.0) — deterministic measurement/assertion over vision guessing
- [youichi-uda/blender-mcp-pro](https://github.com/youichi-uda/blender-mcp-pro) — lazy tool-category loading with an eager fallback
- [RFingAdam/mcp-blender](https://github.com/RFingAdam/mcp-blender) (AGPL; ideas only, no code) — main-thread timer dispatch, tool taxonomy
- [sandraschi/blender-mcp](https://github.com/sandraschi/blender-mcp) (MIT) — portmanteau tool design
## License
MIT — see [LICENSE](LICENSE).
Note on the addon: Blender add-ons using the `bpy` API are considered GPL-derivative by the Blender Foundation. MIT is GPL-compatible, so this poses no conflict, but when the addon is distributed together with Blender it is effectively governed by GPL-compatible terms.
