Blender has had a Python API for two decades, which means almost anything you can click in Blender, a script can do: add a mesh, bevel it, assign a material, aim a light, set Cycles samples, render a frame. What changed in 2026 is that Claude can now write and run that Python inside your open scene, through an MCP server built by Blender’s own developers. You describe the shot in plain language in Claude Code, Claude inspects the scene, builds it in code, renders a draft, looks at the result and fixes what is wrong.
This guide covers the official route as of October 27, 2026: what the Blender Lab connector is, how to install its add-on, how to register its server in Claude Code (which, unlike Claude Desktop, has no connector directory), how to write a scene prompt Claude can execute well, how the two render tools behave, what a prompt-built model costs, and how to keep your files safe from code you did not write.
In this article
1.What the Official Blender Connector Is
The Blender connector is an MCP server published by Blender Lab, the experimental arm of the Blender project. Anthropic announced it on April 28, 2026 as one of nine creative-tool connectors, in its Claude for Creative Work post that states plainly that “the Blender developers have created an MCP connector”. Anthropic also gave Blender a one-time donation toward Python API development. Because the server speaks the open Model Context Protocol, it is not tied to Claude: Blender Lab documents it with llama.cpp as well.
The design matters for everything that follows, so it is worth understanding before you install anything. The project has two parts that run as separate processes. The first is a Blender add-on, named simply “MCP”, that runs inside Blender and opens a TCP socket on localhost:9876. The second is a Python program called blender-mcp that your MCP client starts over standard input and output. When Claude calls a tool, blender-mcp turns the call into Python source, sends it over the socket, the add-on runs it with full access to bpy, and the result comes back as JSON.
The sequence below follows one request from your prompt to a rendered file. Inspection, building and rendering all travel the same path; only the tool name and the Python payload change.
This official server is not the same project as ahujasid/blender-mcp, the community add-on that has circulated since 2025 and that most older tutorials describe. The community version installs with uvx blender-mcp, ships its own addon.py, and adds integrations such as Poly Haven and Hyper3D asset generation. It also listens on port 9876 by default. If you have it installed, disable its add-on before enabling the official one, or the two will compete for the same port and you will spend an evening debugging the wrong server.
The official server does not generate meshes from a text-to-3D model. Everything Claude makes, it makes by writing Blender Python: primitives, modifiers, Geometry Nodes, materials, lights and cameras. That is a limitation for organic characters and a strength for anything procedural, mechanical or architectural, because the result is an ordinary, fully editable .blend file rather than a frozen mesh.
2.Install the Add-on and Start It Inside Blender
The add-on is the half of the connector that lives inside Blender. It needs Blender 5.1 or newer: the add-on’s own manifest sets blender_version_min = "5.1.0", and the Blender Lab page lists 5.1 as the first requirement. Some third-party guides and one Claude tutorial mention older versions; trust the manifest, because Blender will refuse to enable an extension below its minimum version.
Installation happens by drag and drop. Open the MCP Server page on blender.org in a browser next to Blender and drag the add-on install link into the Blender window. The first drop adds the Blender Lab extension repository, which is what lets Blender tell you when a new version of the add-on ships. Drag the same link a second time to install the add-on itself. If drag and drop is awkward on your setup, download the zip and use Install from Disk in the add-on preferences instead.
Next, open Edit > Preferences > Add-ons and find the entry named MCP. Its panel holds three settings that matter: Host, which should stay localhost; Port, which defaults to 9876; and Auto Start. With Auto Start on, the add-on opens its socket every time Blender launches. With it off, you press the start button in the panel at the beginning of every session, and forgetting that step is the single most common reason a first connection fails.
The panel tells you the server is running once the socket is open. You can confirm it from a terminal too, which is useful when you are not sure whether an old community add-on is holding the port. The command below lists whatever process is listening on 9876; you should see Blender, not Python.
Bash
lsof -iTCP:9876 -sTCP:LISTENIf the port belongs to something else, change the port in the add-on panel and remember the new number, because you will pass it to the server in the next step. If nothing is listening, the add-on is not started. Every tool call Claude makes will then fail with the server’s own message, “Cannot connect to Blender”, which is the add-on telling you exactly that.
3.Register blender-mcp in Claude Code
Claude Desktop installs the connector from its Customize > Connectors directory in two clicks. Claude Code has no such directory, and claude mcp add-from-claude-desktop does not import directory connectors, because it reads only the Desktop app’s JSON config. So in Claude Code you register the blender-mcp process yourself with claude mcp add, as described in the Claude Code MCP documentation. There are two sources for that process, and both end in the same tool list.
The cleanest route is to run the server from Blender Lab’s source with uv, which is also how the project’s own MCP bundle launches it. The server package lives in the repository’s mcp/ folder, requires Python 3.10 or newer, and installs one entry point called blender-mcp. The commands below clone the repository once, then add it to the current project. The -- separator matters: everything after it is the command Claude Code runs, passed through untouched.
Install
git clone https://projects.blender.org/lab/blender_mcp.git ~/src/blender_mcp
claude mcp add --scope project --transport stdio blender -- uv run --directory ~/src/blender_mcp/mcp blender-mcp
claude mcp list--scope project writes the entry to .mcp.json in the project folder, so a teammate who opens the same repository gets the same server. Use --scope user instead if you want Blender available in every project on your machine. If you changed the add-on’s port, pass it with --env BLENDER_MCP_PORT=9877, placed before --transport so the CLI does not mistake the server name for another variable. If you want the background tools that open a .blend file without the GUI, also pass --env BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender, because those tools call blender --background and default to whatever blender is on your path.
If you already installed the connector in Claude Desktop, you can point Claude Code at the copy Desktop installed instead of cloning. On macOS it sits inside ~/Library/Application Support/Claude/Claude Extensions/, in a folder whose name contains blender-mcp, with the executable at .venv/bin/blender-mcp. Register that absolute path after the --. The tradeoff is that Desktop updates it on its own schedule, so the version Claude Code runs can change without you noticing.
Once claude mcp list shows the server connected, start a Claude Code session with Blender open and run a read-only check. The server exposes 28 tools under the mcp__blender__ prefix, and the path-info tool is the quickest proof that all three processes are talking to each other.
A correct answer names your file (or reports an unsaved new file) and the active engine. If Claude says the tools are missing, run /mcp inside the session to see the server’s status. If the tools exist but every call fails, go back to the add-on panel: the server process started, but nothing is listening on the port it is dialing.
4.Write a Scene Prompt Claude Can Build
The server ships its own instructions, which Claude receives on connection, and they shape how a good prompt should look. They tell the model to inspect the scene before acting, never to assume missing values, not to make destructive changes without confirmation, to prefer standard operators for ordinary actions, and to treat execute_blender_code as a last resort when no dedicated tool fits. In practice that last rule rarely applies to building, because there is no “add a cube” tool: construction always goes through generated Python. What the rules do mean is that Claude will look before it builds, and a prompt that gives it something concrete to check against gets better results.
The most useful habit is to write the prompt like a production brief rather than a wish. Name the objects and their real-world sizes, the materials, the lights, the camera and lens, the render engine, the resolution and where the result should go. Then ask for the work in stages with a report after each one, so a wrong assumption in the blockout does not get buried under materials and lighting. The prompt below builds a small product shot in four stages; paste it into Claude Code with an empty scene open.
Build a studio product shot in a new collection called “ProductShot”, in four stages, and report after each stage with get_objects_summary:
1. Blockout: a matte ceramic coffee mug, 9.5 cm tall and 8 cm wide, with a handle, standing on a seamless curved backdrop (sweep) 2 m wide. Use real-world metres, apply scale, add a bevel modifier to the mug rim.
2. Materials: Principled BSDF only. Mug: off-white ceramic, roughness 0.35. Backdrop: warm grey, roughness 0.8.
3. Light and camera: one large area key light at 45 degrees camera-left, one smaller rim light behind camera-right, a 85 mm camera at mug height framing the mug at about 60% of frame height.
4. Render settings: Cycles, 1920×1080, 128 samples with denoising.
Do not delete or modify anything outside the ProductShot collection. Return structured results, not print output.
Each stage turns into one or more execute_blender_code calls. The tool runs the Python in the live session and returns whatever dictionary the code assigns to a variable named result, which is why the prompt asks for structured results: Claude can check its own work from returned values such as object names, dimensions and modifier stacks instead of guessing. The instructions also warn the model that operators depend on the current mode, the active object and the selection, and that edit-mode geometry must go through bmesh and be flushed back. When a build silently does nothing, one of those three is usually the cause, and asking Claude to “set object mode and the active object explicitly before each operator” fixes it.
Check each stage before you let Claude continue. The get_objects_summary report should list the ProductShot collection with the mug, backdrop, two lights and camera, and get_object_detail_summary on the mug should show dimensions close to 0.08 by 0.095 metres with scale applied. For framing, ask for get_screenshot_of_area_as_image on the 3D viewport from the camera view. That screenshot comes back to Claude as an image it can read, so it can compare the framing to the brief and adjust the camera before any render time is spent.
5.Render Drafts, Then the Final Frame
The server has two render tools, and they are built for different moments. render_thumbnail_to_path makes a quick draft: it scales the longest side of the frame to 320 pixels, turns on Simplify with one subdivision level, drops Cycles or Eevee to 16 samples, renders, then restores every setting it changed. render_viewport_to_path renders the scene with your actual render settings, at full resolution and full sample count. In an interactive session both start the render without blocking Blender’s interface and report back when the image file appears.
Both tools also share a detail that catches people out. Whatever path you give them, they keep only the file name and write the image into a blender_mcp folder inside Blender’s temporary directory (bpy.app.tempdir). Ask for ~/Desktop/mug.png and you get a file called mug.png in a temp folder that Blender deletes when it quits. The tool returns the real path, so nothing is lost, but if you want the file kept, ask Claude to copy it out in the same turn.
The workflow that wastes the least time is a draft loop followed by one final render. While you are still changing lights, materials or framing, ask only for thumbnails, which on a simple scene usually finish in seconds. When the draft looks right, render the final and save it into the project. The prompt below does both steps and makes the save explicit.
When I reply “final”, render with render_viewport_to_path, then use execute_blender_code to copy the rendered PNG to //renders/mug_final.png next to the .blend file and return the saved path and image size.
The // prefix is Blender’s notation for “relative to the current .blend file”, so the copy lands in a renders folder beside your project. That only works once the file has been saved at least once; on an unsaved scene, ask Claude to save the .blend first. Confirm the result by opening the returned path: a correct final matches the scene resolution exactly, 1920 by 1080 in the brief above. A thumbnail that looks right but a final that comes out black or noisy usually points at a setting the thumbnail overrode, such as samples or Simplify, rather than at the scene itself.
6.What a Prompt-Built Model Costs
Rendering costs only machine time, because the renderer runs locally. The real expense of this workflow sits in the model: every stage of building means Claude reading the scene, writing Python, reading the result and often trying again. The longer and more detailed the build, the more of that loop you pay for, and the effort level you run Claude at multiplies it.
The clearest public example comes from the creator Mr Tactical, who gave Claude Opus 5.5 the same prompt twice: build an animated wooden cannon tower for a tower defence game, entirely from scratch in Blender, with no imported assets. At Low effort the build took 12 minutes and cost about $2.30. At Max effort it took 105 minutes and cost about $29.30, roughly 13 times as much. Those are one creator’s numbers from one prompt, not a benchmark, but the ratio shows where your money goes: more reasoning per step and more refinement passes, not more rendering.
Claude Opus 5.5: Low vs Max effort
Same prompt. Same model. An animated cannon tower built from scratch in Blender, all code, zero assets.
– Low: 12 min, ~$2.30
– Max: 105 min, ~$29.30Was Max worth 13x the price?
Follow or I'll set your AI to Low effort… https://t.co/MVL5bGcECx pic.twitter.com/vZmNVVopnZ
— Mr Tactical (@MrTacticalX) October 19, 2026
Three habits keep the bill predictable. First, choose effort per stage: a blockout or a renaming pass rarely needs maximum effort, while a tricky Geometry Nodes setup or a mechanism with moving parts might. Second, prefer cheap observations. get_screenshot_of_window_as_json describes the window layout, active object and selection as text, and a 320-pixel thumbnail is far smaller than a full-window screenshot, so ask for those during iteration and save full screenshots for framing checks. Third, keep tool results small. Claude Code warns when a single MCP result passes 10,000 tokens and caps it at 25,000 by default, and a scene summary of a heavy file can get there; ask for summaries of one collection at a time instead of the whole scene.
Check the cost as you go rather than at the end. Claude Code shows session usage, and a stage that runs much longer than the previous ones is usually a loop: Claude retrying an operator in the wrong mode, or rebuilding an object it already made. Stopping it, reading the last error and giving one concrete correction is cheaper than letting it search.
7.Keep the Blend File Safe
Blender Lab is blunt about the main risk. Its MCP Server page carries a security warning that the server executes code generated by a language model inside Blender without any guards to stop that code deleting your data or sending it to a remote location, and it recommends running the setup in a virtual machine or on a system without access to sensitive information. The add-on contains a small sandbox that blocks a few specific operations, but it is not designed to stop file deletion or network access, so treat every execute_blender_code call as a script you are choosing to run.
Working habits do most of the protection. Run the connector on a copy of a project, not on the only version of a client file, and save before each stage so Blender’s own backup files give you a way back. Changes Claude makes live in the open session until you save, which cuts both ways: a bad stage can be undone by reverting, but a crash loses everything since the last save. Keep the prompt’s scope rule, such as “do not modify anything outside this collection”, because the server’s instructions tell Claude to respect existing structure and the scope gives it a concrete boundary to check.
Know the operational limits as well. One MCP client should drive one Blender instance at a time, so do not run Claude Desktop and Claude Code against the same session. The server gives up on a socket request to the add-on after 300 seconds, and the background tools that open a .blend without the interface stop after 120 seconds. For a heavy final frame that takes many minutes, start the render from Blender yourself and let Claude handle the setup and the checks around it. And remember what the tool is: a way to drive Blender’s Python API by describing what you want. It builds editable scenes well, and it does not replace your judgment about whether the render is any good.
