blender-mcp-server 0.1.3

MCP server for controlling Blender via AI assistants

Blender MCP Server

Control Blender from any AI assistant using the Model Context Protocol (MCP).

27 tools across 7 namespaces — create objects, assign materials, render images, export scenes, execute Python scripts, manage async jobs, and more.

How It Works

┌─────────────┐      stdio       ┌──────────────────┐    JSON/TCP     ┌─────────────────┐
│  MCP Client │ ◄──────────────► │  MCP Server      │ ◄─────────────► │  Blender Add-on │
│  (any host) │                  │  (Python)        │  localhost:9876 │  (runs in bpy)  │
└─────────────┘                  └──────────────────┘                 └─────────────────┘

1. The Blender add-on runs inside Blender and listens on localhost:9876.
2. The MCP server connects to your AI client via stdio and forwards tool calls to Blender over TCP.
3. You ask the AI → it calls MCP tools → Blender executes commands → results flow back.

Quick Start

1. Install the MCP Server

git clone https://github.com/djeada/blender-mcp-server.git
cd blender-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

This creates the executable .venv/bin/blender-mcp-server.

2. Install the Blender Add-on

Build the add-on zip:

./scripts/build_addon_zip.sh

Then in Blender:

1. Go to Edit → Preferences → Add-ons → Install.
2. Select dist/blender_mcp_bridge.zip and enable Blender MCP Bridge.
3. In the 3D Viewport, press N → open the MCP tab.
4. Confirm it shows Listening on 127.0.0.1:9876.

3. Connect Your MCP Client

Claude Desktop

Add to your config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server"
    }
  }
}

Replace the path with the actual location of your clone.

Codex CLI

Register the server once:

codex mcp add blender -- /absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

Verify with codex mcp list. Then start Codex from any directory — it launches the server automatically.

Other MCP clients

Point any MCP-compatible client at the server executable:

/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

The server uses stdio transport. No additional flags are needed.

4. Start Using It

Make sure Blender is open with the add-on listening, then ask your AI assistant:

• "What objects are in my Blender scene?"
• "Create a cube named TestCube at [0, 0, 1]"
• "Render the scene to /tmp/render.png"

The AI calls MCP tools like blender_scene_list_objects and blender_object_create, which the server forwards to Blender.

Example Prompts

🔍 Inspecting your scene

• "What objects are in my scene?"
• "Show me the transform of the Camera object"
• "List all materials in the file"

🔨 Creating objects

• "Create a sphere named 'Earth' at position [0, 0, 2] with size 3"
• "Add a cylinder at the origin, then scale it to [0.5, 0.5, 4] to make a tall pillar"
• "Create 5 cubes in a row spaced 3 units apart"

🎨 Materials & colors

• "Create a red material and assign it to the Cube"
• "Make a material called 'Ocean' with color [0.0, 0.3, 0.8] and assign it to the Sphere"
• "Change the color of 'RedMaterial' to orange"

📐 Transforming objects

• "Move the Cube up 2 units on the Z axis"
• "Rotate the Cylinder 45 degrees on the Z axis"
• "Scale the Sphere to [2, 2, 2]"

📸 Rendering & exporting

• "Render the scene at 1920×1080 and save it to /tmp/render.png"
• "Export the scene as a GLB file to /tmp/scene.glb"

🐍 Python execution

• "Run this Blender Python: bpy.ops.mesh.primitive_monkey_add(location=(0,0,2))"
• "Execute the fluid_domain.py script from the library with resolution 128"
• "Start an async bake job for the fluid simulation and tell me the job ID"

⏪ Undo / Redo

• "Undo the last change"
• "Redo what was just undone"

Tool Reference

Scene Inspection

Tool	Description
blender_scene_get_info	Scene metadata — name, frame range, render engine, resolution, object count
blender_scene_list_objects	List all objects, optionally filter by type (MESH, CAMERA, LIGHT, …)
blender_object_get_transform	Get position, rotation, and scale of an object by name
blender_object_get_hierarchy	Parent/child hierarchy tree (full scene or subtree)

Object Manipulation

Tool	Description
blender_object_create	Create primitives: cube, sphere, cylinder, plane, cone, torus
blender_object_delete	Delete an object by name
blender_object_translate	Move — absolute location or relative offset
blender_object_rotate	Set rotation [x, y, z] in degrees (default) or radians
blender_object_scale	Set scale [x, y, z]
blender_object_duplicate	Duplicate with optional new name

Materials

Tool	Description
blender_material_list	List all materials in the file
blender_material_create	Create a material with optional base color [r, g, b] (0–1)
blender_material_assign	Assign a material to an object
blender_material_set_color	Set the Principled BSDF base color
blender_material_set_texture	Set an image texture as base color

Rendering & Export

Tool	Description
blender_render_still	Render still image — output path, resolution, engine
blender_render_animation	Render animation — frame range, output path, engine
blender_export_gltf	Export as glTF/GLB
blender_export_obj	Export as OBJ
blender_export_fbx	Export as FBX

History

Tool	Description
blender_history_undo	Undo the last operation
blender_history_redo	Redo the last undone operation

Python Execution

Tool	Description
blender_python_exec	Run a Python script synchronously. Accepts code or script_path, optional args, timeout_seconds, and transport (bridge or headless).
blender_python_exec_async	Start a long-running script asynchronously. Returns a job_id.
blender_job_status	Poll an async job's status, result, stdout, stderr, and error.
blender_job_cancel	Cancel a running or queued async job.
blender_job_list	List known async jobs with IDs, status, and creation time.

Script Library

Pre-built scripts in scripts/library/ for use with blender_python_exec via script_path:

Script	Description
create_mesh.py	Create primitive meshes through the data API (no bpy.ops)
fluid_domain.py	Create a Mantaflow fluid domain
fluid_inflow.py	Create an inflow source
effector.py	Set objects as collision effectors
rigid_body.py	Add rigid body physics
frame_range.py	Set scene frame range
camera.py	Create and configure a camera
keyframes.py	Insert transform keyframes
collections.py	Organize objects into collections
apply_transforms.py	Apply transforms to objects
save_blend.py	Save the .blend file

See scripts/library/README.md for full argument docs and a dam-break walkthrough.

Tips for physics workflows:

• Prefer create_mesh.py (data API) over bpy.ops.mesh.primitive_*_add in live sessions — the operator path can destabilize view-layer updates around fluid setup.
• Keep Mantaflow liquid modifiers hidden in the viewport to avoid crashes in Blender 4.x.
• Use transport="headless" for heavy physics bakes — this runs scripts in a separate blender -b process.

Safety & Security

Feature	Description
Automatic undo push	Mutation tools push an undo step before executing (Python exec excluded for stability).
Safe Mode	Restricts file I/O to the project directory only.
Tool whitelist	Limits which commands the bridge accepts.
Script path restrictions	script_path must be under configured approved roots.
Inline code toggle	Disable inline code execution via add-on preferences.
Module blocklist	subprocess, shutil, socket, webbrowser, ctypes, multiprocessing are blocked by default.

Add-on Preferences

In Blender → Edit → Preferences → Add-ons → Blender MCP Bridge:

Setting	Default	Description
Safe Mode	Off	Restrict file I/O to the project directory
Port	9876	TCP port for the MCP bridge
Allow Inline Code	On	Allow python.execute to run inline code strings
Approved Script Roots	(blend file dir)	Semicolon-separated directories for script file access

Advanced Usage

Direct bridge testing (no MCP client)

The helper scripts in scripts/ connect directly to the Blender add-on on 127.0.0.1:9876, bypassing the MCP server entirely. Useful for verifying the add-on works:

python3 scripts/blender_scene_info.py
python3 scripts/blender_create_test_cube.py --name TestCube --x 0 --y 0 --z 1 --size 2
python3 scripts/blender_bridge_request.py scene.get_info
python3 scripts/blender_bridge_request.py object.translate --params '{"name":"TestCube","offset":[0,0,2]}'

All scripts accept --host, --port, and --timeout flags.

Headless / background mode

Run Blender without a GUI for automation:

blender -b --python your_script.py

Where your_script.py starts the MCP bridge:

import sys
sys.path.insert(0, "/path/to/blender-mcp-server")
from addon import CommandHandler, BlenderMCPServer

server = BlenderMCPServer()
server.start()

import socket
s = socket.socket()
s.bind(("127.0.0.1", 9877))
s.listen(1)
s.accept()  # Blocks until shutdown signal

Programmatic tool call examples

Inline code — create a fluid domain:

{
  "tool": "blender_python_exec",
  "args": {
    "code": "import bpy\nbpy.ops.mesh.primitive_cube_add(size=4, location=(0,0,2))\ndomain = bpy.context.active_object\ndomain.name = 'FluidDomain'\nbpy.ops.object.modifier_add(type='FLUID')\ndomain.modifiers['Fluid'].fluid_type = 'DOMAIN'\nsettings = domain.modifiers['Fluid'].domain_settings\nsettings.domain_type = 'LIQUID'\nsettings.resolution_max = 64\n__result__ = {'domain': domain.name, 'resolution': 64}",
    "args": {"resolution": 64}
  }
}

Script file — set up colliders:

{
  "tool": "blender_python_exec",
  "args": {
    "script_path": "scripts/library/effector.py",
    "args": {
      "objects": ["Ground", "Building_01", "Building_02"],
      "effector_type": "COLLISION"
    }
  }
}

Async bake and poll:

{"tool": "blender_python_exec_async", "args": {"code": "import bpy\nbpy.ops.fluid.bake_all()\n__result__ = {'baked': True}", "timeout_seconds": 1800}}

→ {"job_id": "job-f8e2a1b3"}

{"tool": "blender_job_status", "args": {"job_id": "job-f8e2a1b3"}}

Development

git clone https://github.com/djeada/blender-mcp-server.git
cd blender-mcp-server
pip install -e ".[dev]"

pytest tests/ -v

Project Structure

blender-mcp-server/
├── addon/                        # Blender add-on (TCP server + command handlers + job manager)
├── src/blender_mcp_server/       # MCP server (stdio transport + tool definitions)
├── scripts/
│   ├── library/                  # Reusable Blender scripts for common tasks
│   ├── demos/                    # End-to-end demo scenes
│   └── blender_bridge_request.py # Direct bridge test helpers
├── tests/                        # Unit tests (mocked bpy, no Blender required)
├── docs/                         # Architecture & design docs
├── pyproject.toml
└── README.md

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Add tests for your changes.
4. Run pytest tests/ -v to verify all tests pass.
5. Submit a pull request.

License

MIT