Blender MCP — Pitfalls & Lessons Learned

All interaction goes through the blender MCP tools (hermes mcp install blender): get_scene_info, get_object_info, get_viewport_screenshot, and execute_blender_code for arbitrary bpy Python.

Setup & Connection

1. The addon bridge must be started BEFORE the tools work

The Blender MCP addon opens its local bridge socket only when you click "Connect to Claude" in the BlenderMCP sidebar tab (N-panel). If the MCP tools error with "connection refused", the addon isn't connected — fix that in Blender, don't retry the tool.

Verify the bridge is up: lsof -i :9876 -P -n | grep LISTEN

2. Port 9876 is the addon's default — check for conflicts

Other services may already use 9876. If the tools fail but Blender is running with the addon started, check with lsof. The port is configurable in the BlenderMCP addon UI panel.

3. Addon installation requires user interaction

Blender addon installation requires the GUI: Edit > Preferences > Add-ons > Install. The agent cannot automate this. Provide the addon.py path and let the user install it.

Python Execution (execute_blender_code)

4. Only bpy and math are in the namespace

The code runs in a namespace with only bpy and math. If you need os, json, bmesh, mathutils, etc., import them inside the code:

import bmesh
bm = bmesh.new()
...

5. Code result is always empty in Blender 5.x

The addon returns {"executed": true, "result": ""} for ALL code — the eval result is not captured in Blender 5.x. To get values out:

• Use get_scene_info or get_object_info for queries
• Write results to a temp file and read back:

import json
open('/tmp/result.json', 'w').write(json.dumps([o.name for o in bpy.data.objects]))

6. Errors come back as error strings — always check

The addon catches exceptions and returns them as error text rather than crashing. Check the tool result for an error before assuming the code ran.

7. bpy.ops require correct context

Many bpy.ops functions require the right UI context, which differs when executing through the bridge. Prefer direct data manipulation:

# Prefer data API over ops
bpy.data.objects.remove(bpy.data.objects['Cube'], do_unlink=True)

Objects & Scene

8. Default scene has Cube, Light, Camera

New Blender files start with a Cube at (0,0,0), a Light, and a Camera. Clear them before building.

9. Object names are unique — Blender auto-renames duplicates

Creating an object named "Cube" when one already exists results in "Cube.001". Always check the actual name via get_scene_info.

10. Degrees vs radians

The addon's own object-creation commands take degrees and convert internally, but bpy code in execute_blender_code uses radians. Be careful about the distinction.

Materials

11. Principled BSDF is the default shader

Materials created by the addon use Principled BSDF. For other shader types, build the node tree manually in execute_blender_code.

12. Color is RGBA 0-1, not RGB 0-255

Material colors use floating-point RGBA in the 0.0-1.0 range.

Rendering

13. Render blocks the bridge — expect long calls

Rendering is synchronous; the tool call won't return until the render finishes. Expect renders to take far longer than other calls.

14. Engine name varies by Blender version

In Blender 5.x, EEVEE is 'BLENDER_EEVEE' (not 'BLENDER_EEVEE_NEXT', which was Blender 4.x). Discover available engines at runtime:

import json
open('/tmp/engines.json', 'w').write(json.dumps(
    list(bpy.types.RenderSettings.bl_rna.properties['engine'].enum_items.keys())))

Known engine names: BLENDER_EEVEE, BLENDER_WORKBENCH, CYCLES

15. GPU rendering requires explicit setup on macOS

Use METAL compute device type on Apple Silicon. Use CUDA or OPTIX on NVIDIA.

Reliability

16. All state lives in Blender's scene data

Each tool call is independent — there is no session state in the bridge. Anything you need later must exist in the scene (or a file you wrote).

17. Blender crash loses the bridge

If Blender crashes, relaunch it, re-enable the addon, and click "Connect to Claude" again. Save frequently (bpy.ops.wm.save_mainfile()).