Setup
Install Blender 5.1 or newer and the official Blender Lab connector, connect Claude Desktop or Claude Code, and avoid the traps that stop it working.
Use Blender 5.1 or newer with the official Blender Lab connector. Turn on Allow Online Access in Blender, or the connector never connects. Run it on a machine without sensitive data, because it has no real sandbox.
What you need
- Blender 5.1 or newer. The add-on manifest sets the minimum to 5.1.0 and the Blender Lab page says the same. Anthropic's tutorial still says 4.2 or later; trust the manifest. Organic Opus 5.5 guides use 5.2.2.
- Claude Desktop or Claude Code on the same computer as Blender. The connector works on every Claude plan, including Free, but not on claude.ai in the browser.
- Opus 5.5 at high effort. That is what the detailed creator guides use.
Which connector
Two projects have almost the same name. Pick one.
| Official "Blender" connector | Community "MCP for Blender" | |
|---|---|---|
| Made by | Blender Lab (Blender developers), GPL 3.0 | Siddharth Ahuja (ahujasid), MIT, not affiliated with Blender |
| Blender version | 5.1 or newer | 3.0 or newer |
| Tools | 26: code, screenshots, renders, scene and file summaries, docs lookup | 9, including multi angle views and 3D asset import |
| Telemetry | None mentioned | Anonymous usage record on by default |
| Default port | localhost:9876 | localhost:9876 |
Use the official connector. Anthropic ships it in Claude Desktop, and the most detailed Opus 5.5 guides use it. It launched on 28 Apr 2026 with Claude for Creative Work. Add asset sources separately (BlenderKit, Meshy, Tripo, or a local generator), see Consistent scenes. The community server is the better pick only if you want asset import and multi angle views in one tool and accept its telemetry default.
What the 26 tools do
Claude talks to a small server on your computer. That server sends Python to the add-on inside Blender over localhost:9876 and waits up to 300 seconds for an answer. Every tool is "send code to Blender"; the summary tools are Python written in advance.
| Group | Tools | What they do |
|---|---|---|
| Run code (2) | execute_blender_code, execute_blender_code_for_cli | Run Python with full bpy access in the open Blender, or in a separate background Blender (120 s timeout, needs BLENDER_PATH) |
| Screenshots (3) | get_screenshot_of_window_as_image, get_screenshot_of_area_as_image, get_screenshot_of_window_as_json | A PNG of the whole window or of one editor (3D view, Graph Editor, node trees), or the window layout and selection as JSON. Images are downscaled to about 786 KB |
| Render (2) | render_viewport_to_path, render_thumbnail_to_path | A full render with the scene settings (despite the name, not a viewport capture), and a small preview render |
| Scene (2) | get_objects_summary, get_object_detail_summary | The collection tree, and one object's transforms, modifiers, materials and constraints |
| File (10) | Five get_blendfile_summary_* tools, each with a _for_cli twin | Data block counts and render engine, a guess at what the file is for, missing files, save status, linked libraries |
| Navigate (4) | jump_to_tab_by_name, jump_to_tab_by_space_type, jump_to_view3d_object_by_name, jump_to_view3d_object_data_by_name | Switch workspace or frame an object in the 3D view |
| Docs (3) | get_python_api_docs, search_api_docs, search_manual_docs | Look up the bundled Blender 5.x Python API and user manual |
The docs tools matter most. Code written for Blender 3.x or 4.x often breaks on 5.x, so tell Opus to check an API before it uses it.
Install for Claude Desktop
Install Blender 5.1 or newer
Version 5.2.x is in current use.
Add the connector
In Claude Desktop open Customize, then Connectors, search for "Blender" and click Add.
Install the add-on in Blender
On the Blender Lab MCP page, drag the install link into Blender twice. The first drag adds the lab.blender.org extension repository, the second installs the "MCP" add-on (currently mcp-1.0.3.zip). You can also download the zip and use Install from Disk.
Turn on Allow Online Access
In Blender open Edit, Preferences, System and tick Allow Online Access.
Start the bridge
In Edit, Preferences, Add-ons, MCP, click "Start MCP Bridge Server", or tick Auto Start. Without Auto Start you must start it every session.
Test it
Ask Claude: "List the collections and objects in the open scene." It should call get_objects_summary and answer with your scene.
Allow Online Access must be on
If it is off, the add-on never opens port 9876 and only shows a small red label. Claude then says it cannot connect to localhost:9876. Check this setting first whenever the connection fails.
Two install failures are reported: the .mcpb file fails on macOS with "Operation not permitted" (issue 57, open), and Windows Smart App Control blocks it (issue 56). If that happens, use the manual setup below.
Install for Claude Code
The project documents a generic setup. In Claude Code form:
cd "$HOME" && git clone https://projects.blender.org/lab/blender_mcp.git
claude mcp add blender -- uv --directory "$HOME/blender_mcp/mcp" run blender-mcpYou need uv and Python 3.10 or newer. Then start Blender, do steps 3 to 5 above, run /mcp in Claude Code to confirm that blender is connected, and pick Opus 5.5 at high effort.
- Background renders. Set
BLENDER_PATHto your Blender program so the_for_clitools can startblender --background. - Old clones. Version 2 of the MCP Python SDK broke the server at startup in August. Version 1.0.2 pins it below 2, so pull the latest code if you cloned earlier.
Safety: there is no sandbox
Blender Lab says plainly that the server runs AI generated code in Blender without guards, and suggests a virtual machine or a computer without sensitive data. Python inside Blender can read and write files, open network connections and run programs.
- Use a VM for untrusted work. The add-on's "weak sandbox" only blocks
sys.exit, quitting and three preference or factory resets. Its own code comment calls it a slap on the wrist. - Keep the port on localhost. The socket has no password. Anyone who can reach it can run Python. The official add-on binds to localhost by default; do not change that.
- Save versions. Changes live in the session until you save. Save an incremented copy before each big step.
- Read before it runs. Ask Claude to show the Python before running anything destructive. In Claude Code, leave
execute_blender_codeon "ask" unless the project is disposable. - Untrusted .blend files can carry scripts. Keep Blender's auto run of scripts off for files from other people.
- API keys for asset services (Meshy, Tripo, Hyper3D and others): type them yourself into add-on preferences or environment variables, never into the chat.
Do not run both connectors at once
The community "MCP for Blender" server listens on the same port, 9876. Enable only one add-on at a time, or move one to another port (the official server reads BLENDER_MCP_HOST and BLENDER_MCP_PORT). The community server also sends an anonymous usage record by default; set DISABLE_TELEMETRY=true if you use it.
Versions (checked 15 Oct 2026)
| Part | Version | Note |
|---|---|---|
| Blender | 5.1 or 5.2.x | Scripts for 3.x and 4.x often fail on 5.x |
| Add-on "MCP" | 1.0.3 (11 Sep 2026) | Fixes the screenshot tool |
| Server (upstream) | 1.0.3 | |
| Claude Desktop extension | 1.0.1 on the machine we inspected | The package inside even reports 1.0.0. Check Claude Desktop for an update |
Version 1.0.1 still has the screenshot bug on macOS and Retina displays. If screenshots fail, update the add-on and the connector to 1.0.3.
Known connector bugs
| Bug | What happens | Workaround |
|---|---|---|
| Render path ignored | Both render tools ignore the folder you pass and write to Blender's temp folder (blender_mcp inside bpy.app.tempdir). The tool result gives the real path | Have Claude set scene.render.filepath (for example //renders/03/clay/) and render with execute_blender_code, or copy the files afterwards |
| Output path saved by mistake | A tool render changes the scene output path for a moment; saving during the render can store the temp path (issue 12) | Do not save while a tool render runs |
| Thumbnail at full size | render_thumbnail_to_path should render at 320 px with 16 samples but renders at full resolution in a live Blender (issues 46 and 61, open) | Set resolution and samples yourself before any preview render |
| Old EEVEE engine name | The installed code caps EEVEE samples only for the engine id BLENDER_EEVEE_NEXT, but Blender 5.x calls it BLENDER_EEVEE, so the cap likely never applies (read from the code, not tested) | Same as above |
| Screenshots fail on macOS | Retina displays broke screenshots before 1.0.3 (issues 21 and 49) | Update to 1.0.3 |
_for_cli tools hang on Windows | The background Blender inherits the connection pipe (issues 58 and 60) | Run background renders yourself from a terminal |
| Connection drops on heavy scenes | A short client timeout dropped complex scenes (issue 28, closed) | The maintainer says 1.0.3 may have fixed it; keep steps small |
Sources
- Blender Lab MCP server
- Blender MCP source and issues
- Blender MCP setup wiki
- Weak sandbox source
- Anthropic Academy: using the Blender connector
- Anthropic: Claude for Creative Work
- Community MCP for Blender README
- Creator setup guides: rewind02 (templated account), tetumemo (organic)