Blender MCP with Claude Code
Connect Claude Code to Blender MCP, inspect a test scene, and verify edits with previews; review Python before running it.
TL;DR
“Blender MCP” is a category, not one official server. Pick a maintained repository and follow its exact add-on, launcher, and port instructions.
Claude Code launches an MCP server, while a Blender add-on bridges tool calls into the live Blender application.
Work on a copy, name objects and collections, apply one logical change, inspect scene state, save a checkpoint, then render a preview.
Any tool that executes arbitrary Blender Python can modify scenes, files, add-ons, and system-accessible resources. Review it before running.
The reliable pattern is: select one documented implementation, prove the local bridge on a disposable scene, expose only the tools needed for the current task, and make every scene change observable through object state plus a saved file or preview render. Do not begin by granting arbitrary Python against an important .blend file.
Set up Blender MCP with Claude Code
Commands, ports, authentication, and tool names vary across Blender MCP repositories. This guide uses the community BlenderMCP repository as a concrete example because it documents a Blender add-on, a uvx-launched MCP server, Claude Code setup, scene inspection, viewport screenshots, and local socket behavior. It is not affiliated with the Blender Foundation, so verify the current repository instructions before installing.
For this implementation, confirm a supported Blender release, compatible Python, uv/uvx, and current Claude Code. Run uvx --version and claude --version in the same terminal. If a GUI-launched client cannot find uvx, use the full executable path and relaunch the client.
Download the add-on file from the selected repository, install it through Blender Preferences, enable “Interface: Blender MCP,” open the 3D View sidebar, and use the BlenderMCP panel to start the connection. Test on a new scene, not an existing production asset.
Add the server in the target project with claude mcp add --transport stdio --scope local blender -- uvx blender-mcp. The double dash keeps Claude Code options separate from the server launcher. Use local scope until the integration and permissions are understood.
Blender must be open with the add-on connected, and Claude Code must show the blender server as healthy. Check claude mcp list, claude mcp get blender, and the in-session /mcp panel before requesting any scene mutation.
Keep the add-on and MCP package in sync
The selected project documents a paired Blender add-on and MCP package. When upgrading, update both sides together, restart Blender and Claude Code, reconnect the add-on, and repeat a read-only scene inspection before editing. A version mismatch can appear as missing tools, malformed responses, timeouts, or calls that reach the server but not Blender. Record the working add-on and package versions with the project so another machine can reproduce the environment.
A reliable scene-building workflow
| Step | Main action | Check | Guardrail |
|---|---|---|---|
| Contract | State the file, units, allowed collection, object names, dimensions, and final deliverable. | An ordered task contract with explicit exclusions. | Never rely on “make it better” alone. |
| Baseline | Inspect the scene and save a versioned copy before mutation. | Collections, objects, active mode, camera, and output path. | Keep the original file untouched. |
| Execute | Apply one logical change such as geometry, material, lighting, or camera setup. | Tool result and changed object names. | Do not batch unrelated destructive edits. |
| Inspect | Read object state after the change. | Names, transforms, hierarchy, materials, modifiers, and camera settings. | Do not accept a success message as evidence. |
| Preview | Capture the viewport or render a low-cost preview. | Composition, scale, clipping, shadows, and visible artifacts. | Structural checks do not prove visual quality. |
| Checkpoint | Save or export only after the named checks pass. | New file exists, output format is correct, and the previous version remains recoverable. | Require approval before overwrite or final export. |
Give Claude Code a scene contract
A useful prompt reads more like a production brief than a chat request. Identify the starting .blend file, the collection Claude may change, the coordinate and unit assumptions, required object names, target dimensions, material intent, camera framing, output resolution, and the checkpoint that ends the step. Add negative constraints such as “do not delete existing lights,” “do not apply modifiers,” and “do not overwrite the source file.” These details reduce ambiguity and make the resulting scene easier to inspect with Blender's own object and collection model.
Prompt pattern: “Open the working copy, inspect the scene, and report the active camera and objects in Product_Set. Add one object named Pedestal_A at the stated dimensions without changing other collections. Report its transform and material slots, capture a viewport preview, then stop before saving.”
Increase autonomy in stages
Start with read-only inspection. Next, create a disposable primitive, modify one named object, add a material or light, generate a preview, and only then test versioned save or export. Each level proves a different part of the bridge. If the first request combines modeling, asset downloads, Python execution, rendering, and overwriting a file, a failure provides little evidence about which layer broke.
Verify structure and appearance separately
Scene inspection should confirm exact object names, transforms, collection membership, modifier order, material slots, camera settings, render engine, resolution, and output path. A viewport screenshot or preview render then checks composition, occlusion, surface response, lighting, and obvious artifacts. Keep both forms of evidence: a plausible image can hide incorrect hierarchy or dimensions, while a correct object report can still produce a poor frame.
Safety and troubleshooting practices
Work on a versioned copy, keep autosave available, and grant only the tools needed for the current task. Require a pause before saving over an existing file, deleting collections, installing an add-on, downloading an asset, or exporting a final deliverable.
The example server exposes arbitrary Blender Python. Such code can do more than edit geometry: it runs with the permissions of the Blender process and may reach files or network resources available to that process. Read generated code, narrow the task, and avoid using unknown scripts on valuable scenes.
The selected implementation uses a local socket between its MCP process and Blender add-on. Its documented remote mode can listen on all interfaces and does not add authentication, so use it only on a trusted isolated network. Never expose that listener directly to the public internet.
If optional asset or material services are enabled, store their credentials in the supported local configuration rather than prompts, screenshots, or project notes. Give each service the narrowest practical permissions and remove unused keys.
Troubleshoot from Claude Code toward Blender
Run claude mcp list and inspect claude mcp get blender. Confirm the project scope, launcher command, executable path, and server startup output. A process that never starts cannot reach the Blender add-on.
Open Blender normally, confirm the add-on is enabled, open its sidebar panel, start the connection, and verify that both sides use the same host and port. Restart both processes after changing either package version.
Report Blender's current mode, selected object, active object, and collection. Many Blender operations depend on context; an edit that works in Object Mode may fail or affect another target in Edit Mode.
Split the request into smaller sequential changes and inspect after each one. Reduce preview resolution and samples while iterating. A timeout is not permission to repeat a potentially destructive call without checking whether Blender already applied it.
Where QVeris fits in an MCP workflow
Blender MCP handles scene state and mutations inside Blender. QVeris complements it when the same agent needs structured external capabilities. The current QVeris catalog does not expose an exact Blender MCP tool or provider record, so this page links to QVeris Docs and the Playground instead of claiming an unsupported one-click integration.
- Use Blender MCP for object inspection, scene mutation, viewport capture, and Blender-specific execution.
- Use QVeris for complementary external API or tool calls that have a verified catalog record and a clear input/output contract.
- Keep the handoff explicit: validate external data before importing it, then require human approval before overwriting, publishing, or final export.
FAQ
No. “Blender MCP” refers to community implementations. This guide uses one documented repository as an example; review its maintainer, releases, code, issues, and installation steps before use.
For the example implementation, yes. Claude Code launches the MCP process, but the enabled add-on must connect to a running Blender application for scene tools to work.
Write-capable tools can change an open scene, but begin with a versioned copy. Define allowed collections and require inspection plus approval before saving over any existing file.
It can orchestrate tools exposed by the chosen server, including previews or renders when supported. Quality still depends on assets, scene constraints, render settings, and visual review.
Usually the MCP process did not start, was registered in another scope, cannot find uvx, or uses a mismatched package. Check Claude Code first, then the Blender add-on connection.
Use it for a separate structured capability with a verified source and schema. Keep actual scene mutations in Blender MCP, and validate external results before they enter the scene.
References and next steps
BlenderMCP repository
Blender Manual
Claude Code MCP documentation