Blender MCP Reference: Driving Blender with bpy via Hermes

This document teaches bpy idioms and pitfalls for controlling a running Blender instance through MCP tools. It does not cover UI workflows. Use this reference when you need to create or modify meshes, materials, animations, lighting, or renders in Blender.

Prerequisites

Before using any Blender MCP tools, complete these one-time setup steps:

1. Install the MCP server from the Nous catalog:

   hermes mcp install blender
   

   This configures a pinned blender-mcp stdio server with the curated tool set: get_scene_info, get_object_info, get_viewport_screenshot, execute_blender_code.

2. Install the addon inside Blender: Download addon.py from https://raw.githubusercontent.com/ahujasid/blender-mcp/main/addon.py, then go to Blender > Edit > Preferences > Add-ons > Install... > select addon.py, and enable "Interface: Blender MCP".

3. Every session: Start Blender FIRST. In the viewport, press N, open the BlenderMCP tab, and click "Connect to Claude" (this starts the local bridge socket). Then start your Hermes session so the MCP tools are loaded.

General Build Procedure

Follow these steps in order for every scene-building task:

1. Call get_scene_info first – never assume the scene is empty.
2. Build with execute_blender_code in small focused calls (one logical step per call: add objects, then materials, then animation). Large monolithic scripts hit bridge timeout.
3. Verify visually with get_viewport_screenshot between major steps.
4. Render to an absolute path and tell the user where the file is.

Tools Overview

get_scene_info

No parameters. Returns a list of all objects in the current scene. Always call this before modifying the scene.

get_object_info

Parameter: Object name (string). Returns transform and material data for the specified object.

get_viewport_screenshot

No parameters. Returns a screenshot of the current viewport. Use for visual verification between steps.

execute_blender_code

Parameter: Arbitrary bpy Python code (string). This is the primary tool for building and modifying scenes. Required for all creation tasks.

Scene Operations

Clear Scene

Use execute_blender_code with these exact commands:

bpy.ops.object.select_all(action='SELECT')
bpy.ops.object.delete()

Add Mesh Objects

Add primitive meshes with specific parameters. Example:

bpy.ops.mesh.primitive_uv_sphere_add(radius=1, location=(0, 0, 0))
bpy.ops.mesh.primitive_cube_add(size=2, location=(3, 0, 0))
bpy.ops.mesh.primitive_cylinder_add(radius=0.5, depth=2, location=(-3, 0, 0))

Create and Assign Material

Create a new material with nodes, set properties, and assign to an object:

mat = bpy.data.materials.new(name="MyMat")
mat.use_nodes = True
bsdf = mat.node_tree.nodes.get("Principled BSDF")
bsdf.inputs["Base Color"].default_value = (R, G, B, 1.0)
bsdf.inputs["Roughness"].default_value = 0.3
bsdf.inputs["Metallic"].default_value = 0.0
obj.data.materials.append(mat)

Replace (R, G, B, 1.0) with actual color values (0.0 to 1.0).

Keyframe Animation

Set location keyframes for an object:

obj.location = (0, 0, 0)
obj.keyframe_insert(data_path="location", frame=1)
obj.location = (0, 0, 3)
obj.keyframe_insert(data_path="location", frame=60)

Render to File

Set output path, engine, and render:

bpy.context.scene.render.filepath = "/tmp/render.png"
bpy.context.scene.render.engine = 'CYCLES'
bpy.ops.render.render(write_still=True)

Constraints and Caveats

• The addon refuses to start under blender -b (background mode). On a headless machine, use xvfb-run blender; GPU rendering works under Xvfb.
• Break complex scenes into multiple smaller execute_blender_code calls to avoid bridge timeouts.
• Render output paths must be absolute (e.g., /tmp/render.png), not relative. They resolve on the Blender host's filesystem, which is important if Hermes and Blender run on different machines.
• shade_smooth() requires the object to be selected and in object mode.
• execute_blender_code runs arbitrary Python inside Blender with no sandbox – same trust level as a terminal tool. Do not paste untrusted code.
• Do NOT hand-roll raw TCP JSON to port 9876 from execute_code – that was a pre-MCP workaround. MCP tools are the supported path.
• Optional asset-service tools (PolyHaven, Sketchfab, Hyper3D, Hunyuan3D) are disabled by default. Enable them via hermes mcp configure blender if the user has enabled the service in the addon panel.

Failure Modes

• MCP tools missing: Run hermes mcp install blender and start a new session.
• Connection refused from tools: Blender is not running or the addon is not connected. Fix that, don't retry. The addon bridge must be (re)connected each Blender session (N-panel > BlenderMCP > Connect).
• Large monolithic scripts: Hit bridge timeout. Always break work into small calls.
• Render output file not found: Confirm the absolute path and that the render completed.

Additional References

For deeper understanding of bpy patterns, consult these internal references:

• references/bpy-api.md
• references/recipes.md
• references/pitfalls.md

Examples

Clear Scene

Select all objects and delete them.

Add Mesh Objects

Add a sphere (radius 1 at origin), a cube (size 2 at (3,0,0)), and a cylinder (radius 0.5, depth 2 at (-3,0,0)).

Create and Assign Material

Create a new material with a Principled BSDF node, set base color, roughness, and metallic values, then append it to the object.

Keyframe Animation

Set the object's location at frame 1, insert a keyframe, then set a new location at frame 60 and insert another keyframe.

Render to File

Set the filepath to an absolute path like /tmp/render.png, set the engine to CYCLES, and render a still image.