OPEN SOURCE DEEP DIVE
MCP for Blender: 32 tools that make Blender a 3D workspace an LLM can drive
Formerly blender-mcp, a third-party community plugin (the README states on its first screen that it is not made by Blender), MIT licensed, Python, and the highest-starred entry among 3D MCP servers. The PyPI package is now mcp-for-blender, yet uvx blender-mcp still runs and existing configs need no change. Two components only: an addon inside the Blender process runs a socket server that actually executes commands (the only place with bpy, the current scene and the UI thread), while a separate MCP server process translates protocol, joined by JSON over TCP on localhost:9876 by default. We counted the @mcp.tool() decorators in the source: 32, in four layers - perception (get_scene_info, get_object_info, get_viewport_screenshot returning an MCP Image, closing an act-then-look loop), reference lookup (bpy_api_lookup and describe_node_type so the model queries instead of guessing socket order and enum names), execution (execute_blender_code as the escape hatch, set_texture, export_scene to GLB/FBX), and asset retrieval and generation (Poly Haven with semantic search, importing the .blend source and writing attribution properties; Poly Pizza with about 10,600 low-poly models, size normalisation and automatic CC-BY credit; Sketchfab; Hyper3D Rodin text-to-3D and image-to-3D; Tencent Hunyuan3D distinguishing the mainland ai3d endpoint from the international hunyuan one). On security, arbitrary code execution is the design rather than a bug: an optional safe mode (BLENDER_MCP_SAFE_MODE=1) statically validates scripts before running, blocking file access, subprocesses, network and persistent code while modelling, rendering, saving, import and export pass normally, and blocked scripts return to the model with the reason so it can retry. Content telemetry is off by default, and a dedicated disable_telemetry tool can only turn collection off. 29.2k stars. We have not run Blender with this addon locally, so it is graded as pending reproduction.
What it is
MCP for Blender (formerly blender-mcp) is a third-party community plugin, not made by Blender - the README states that disclaimer on its first screen. It does one thing: turn Blender into a 3D workspace an LLM can drive directly. Prompt-assisted modelling, scene assembly, materials and lighting, asset lookup and export, all exposed over the Model Context Protocol to clients such as Claude, Cursor and Codex. MIT licensed, Python, and the highest-starred entry among 3D MCP servers.
The rename is worth noting on its own: the PyPI package moved from blender-mcp to mcp-for-blender, yet uvx blender-mcp still runs the server and existing configs need no change. For a project with tens of thousands of installs, renaming without breaking installed configurations is a decent proxy for engineering maturity.
Architecture: two processes, one TCP socket
The system has exactly two components, cleanly separated:
| Component | Runs in | Responsibility |
|---|---|---|
Blender addon (addon.py) | Inside the Blender process | Starts a socket server in Blender that receives commands and executes them in the bpy context |
MCP server (src/blender_mcp/server.py) | A separate Python process (or container) | Implements MCP toward the client, JSON over TCP toward the addon |
Between them sits a deliberately minimal JSON protocol: commands are objects with a type and optional params, responses carry status plus result or message, default endpoint localhost:9876. The split matters because code execution has to happen inside the Blender process - that is the only place with bpy, the current scene and the UI thread. The MCP server only translates protocol and orchestrates tools. The consequences: Blender must be open, the addon's Start MCP Server must be clicked, and only one MCP server instance may run at a time.
32 tools, and the design is in how they group
We counted the @mcp.tool() decorators in the server source: 32. They are not a flat feature list but four layers, each addressing a different failure mode:
| Layer | Representative tools | What it fixes |
|---|---|---|
| Perception | get_scene_info, get_object_info, get_viewport_screenshot | A model that cannot see the scene edits it blind. The viewport screenshot returns as an MCP Image, closing an act-then-look loop |
| Reference | bpy_api_lookup, describe_node_type | The bpy surface is enormous; socket order and enum names recalled from memory will be wrong, so the model looks them up instead of guessing |
| Execution | execute_blender_code, set_texture, export_scene | The escape hatch: anything no specialised tool covers can still land as Python inside Blender |
| Asset retrieval and generation | Poly Haven (4), Poly Pizza (3), Sketchfab (4), Hyper3D Rodin (4), Hunyuan3D (4) | Models only build primitives; real scenes need CC0 textures, HDRIs, ready-made meshes and generated geometry |
The fourth layer is the most underrated part. It is not "five asset libraries were wired up"; each library's usage semantics were thought through:
- Poly Haven (roughly 2,400 CC0 assets, no key, no account): search is semantic rather than keyword matching - the README's own example is that "couch" finds sofas, and it works in any language. Models are imported from the
.blendthe artist authored rather than the glTF/FBX/USD derivatives, which lose material detail. HDRIs are packed into the file and land in a new world instead of overwriting the lighting you already built. On import,polyhaven_id/url/authors/licenceare written as custom properties so whoever opens the file later can still trace the asset and its artist. - Poly Pizza (about 10,600 low-poly models, including the rescued Google Poly archive): every model is a single self-contained
.glb, geometry is far lighter than Sketchfab's, and downloads acceptnormalize_sizeplustarget_sizeso a chair arrives one metre tall. Around 69% of the catalogue is CC-BY and requires attribution, so the import writes a ready-formatted credit line into thepolypizza_attributionproperty and it is saved into your file. - Hyper3D Rodin and Tencent Hunyuan3D: text-to-3D and image-to-3D with job polling, then import. The Hunyuan path has a real trap - mainland accounts call
ai3d(version2025-05-13, Guangzhou) while international accounts callhunyuan(version2023-09-01, PBR enabled, Singapore), and the wrong endpoint fails withAuthFailure.SignatureFailure. Hence the International (Pro) toggle in the sidebar.
Security: arbitrary code execution is the design, not a bug
execute_blender_code runs arbitrary Python inside Blender, and the README puts it in a Warning block: powerful, potentially dangerous, use with caution in production, always save your work first. This is the unavoidable tension in handing professional software to a model - without arbitrary execution, capability is capped by how much the specialised tools happen to cover; with it, one hallucination can destroy a scene that took dozens of hours.
The answer is an opt-in safe mode (BLENDER_MCP_SAFE_MODE=1): scripts are statically validated before running, blocking direct file reads and writes, subprocess launches, network access and code that keeps running after the script ends, while ordinary Blender work - modelling, materials, rendering, saving, import and export - still passes. Blocked scripts are returned to the model with the reason so it can retry with a corrected version, which matters more than a flat refusal because it preserves the agent's self-correction loop.
Telemetry shows similar restraint: content collection (prompts, generated code, viewport screenshots, scene data, trajectory steps) is off by default and stays off until the user ticks a consent box in the addon preferences. The default record is a minimal anonymous usage line (install ID, session ID, tool name, success, duration, versions, OS, timestamp), and DISABLE_TELEMETRY=true removes even that. There is also a dedicated disable_telemetry tool that can only turn collection off - turning it back on requires a human in Blender's UI.
Friction on the way in: the three most honest sections of the README
- GUI clients do not inherit your terminal PATH. In Claude Desktop, Cursor or VS Code launched from the Dock or Start menu,
"command": "uvx"fails withspawn uvx ENOENTeven thoughuvxworks fine in a shell. The fix is an absolute path, and the client must be fully quit and relaunched afterwards. - uv can pick the wrong Python. On machines with conda (auto-activated base), pyenv or asdf, uv may select an interpreter whose dependencies lack wheels. The README gives the pin directly:
--python 3.11withUV_PYTHON_PREFERENCE=only-managed. - Downloads freeze the UI. Poly Haven assets download on Blender's main thread, so the interface stops responding until the transfer finishes, and file size grows roughly fourfold per resolution step - ask for 1k or 2k unless the asset sits close to camera. Poly Pizza's CDN is behind Cloudflare bot protection and blocks datacenter, VPN and cloud IPs; that "your API key is fine" note is the kind of thing issues teach you.
Where it sits on agientry
Our 3D shelf holds two kinds of things: generative asset pipelines (Tripo, Hunyuan3D, TRELLIS - one prompt or one image in, a mesh out) and bridges that put professional DCC software into the agent loop. MCP for Blender is the highest-starred of the second kind, and it is also a consumer of the first: Rodin and Hunyuan output is imported through its own tools. That is also how it differs from img2threejs, which targets the web rendering stack and produces code; this one targets Blender and produces .blend plus GLB/FBX for people with a real production pipeline. The request to include blender-mcp was correct - it is the most mature open-source sample we have of "an agent can operate professional creative software".
Facts on this page come from the project README (read in full) and the src/blender_mcp/server.py source (all 32 tools checked individually); stars, licence and language come from the GitHub API. We have not run Blender with this addon locally and performed no benchmark or reproduction. How far safe-mode static validation actually reaches, and what the screenshot loop does to multi-step modelling success, remain unquantified, so this entry is recorded as pending reproduction.