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. Every request carries a shared secret that the add-on writes to ~/.blender-mcp/token (mode 0600).
3. You ask the AI → it calls MCP tools → Blender executes commands → results flow back.

Quick Start (macOS & Linux)

Install Blender 3.6+ and Python 3.10+, then:

git clone https://github.com/djeada/blender-mcp-server.git
cd blender-mcp-server
scripts/setup.sh              # venv + MCP server, installs and enables the Blender add-on
scripts/start.sh claude       # opens Blender and a Claude Code session already connected to it

scripts/start.sh codex does the same with Codex, and scripts/start.sh none just opens Blender with the bridge running. Anything after the client name goes to the client, e.g. scripts/start.sh claude "Build a snowman and render it". Stop the Blender it opened with scripts/stop.sh.

start.sh hands the MCP server to the client on the command line, so it changes no client config. To register the server permanently instead, run scripts/setup.sh --register claude,codex,claude-desktop. The scripts find Blender on your PATH, in /Applications/Blender.app, or via BLENDER_BIN.

Demos

Each demo is one prompt, recorded end to end against a live Blender. scripts/record_demos.sh re-records them. Every demo also has a plain Blender Python script, so you can build the same kind of scene without an AI: scripts/run_demo.sh 1 (GUI), --background 1 (render only), or --bridge 1 (send it through the MCP bridge to the Blender that start.sh opened).

	Demo	Client
	Still life from a sentence: object, material and render tools	Claude Code
	Procedural city with Python: blender_python_exec	Codex
	Animate live, render headless: keyframes, then transport="headless"	Claude Code

Manual Setup

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

Download blender_mcp_bridge.zip from the latest release, or build it yourself:

./scripts/build_addon_zip.sh

Then in Blender:

1. Go to Edit → Preferences → Add-ons → Install from Disk (Blender 4.2+ installs it as an extension; older versions as a legacy add-on).
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

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

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

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

docker build -t blender-mcp-server .
docker run -i --rm --network host \
  -v ~/.blender-mcp/token:/home/mcp/.blender-mcp/token:ro blender-mcp-server

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

Tool Reference

Scene Inspection

Object Manipulation

Materials

Rendering & Export

History

Python Execution

Script Library

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

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

blender_python_exec runs arbitrary Python inside Blender, so anything that can talk to the bridge can run code as you. The bridge is therefore locked to clients that can read your token file.

The headless transport runs in a separate blender -b process under the MCP server's user and is not subject to the add-on's preferences. Set BLENDER_MCP_HEADLESS=0 to turn it off.

Add-on Preferences

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

The preferences panel also shows where the auth token file lives.

Advanced Usage

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]}'

BLENDER_MCP_PORT=9876 blender -b --factory-startup --python tests/integration/blender_bridge_harness.py

{
  "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}
  }
}

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

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

{"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 -v                                                    # unit tests, no Blender needed
BLENDER_MCP_INTEGRATION=1 pytest tests/integration --no-cov  # end-to-end against real Blender

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/
│   ├── setup.sh / start.sh / stop.sh  # One-command install and launch (macOS & Linux)
│   ├── run_demo.sh               # Run a demo scene script yourself (no AI)
│   ├── record_demos.sh           # Re-record docs/demos with a real AI client
│   ├── library/                  # Reusable Blender scripts for common tasks
│   ├── demos/                    # Bridge-driven dam-break demo scenes
│   └── blender_bridge_request.py # Direct bridge test helpers
├── tests/                        # Unit tests (mocked bpy) + integration tests (real Blender)
├── docs/                         # Architecture & design docs, recorded demos
├── 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