Blender MCP Bridge

Drive Blender from any AI assistant over the Model Context Protocol. An MCP server (this repo) exposes Blender as tools; a Blender add-on executes them live in your scene.

MCP client (Claude Desktop / Cursor / Muse / ...)
   --stdio-->  server/blender_mcp_server.py
   --TCP 127.0.0.1:9876-->  Blender add-on  -->  bpy  -->  your scene

What you can do with it

• "Create a red metallic sphere at (1, 0, 0)" → create_primitive + create_material + assign_material

• "What's in my scene?" → get_scene_info

• "Show me what it looks like" → get_viewport_screenshot (the AI sees the viewport)

• "Add a subdivision modifier and animate it rotating" → execute_blender_code (raw bpy)

Related MCP server: dcc-mcp-blender

Setup

1. Install the Blender add-on

1. Grab dist/blender_mcp_bridge.zip (or zip addon/blender_mcp_bridge.py yourself).

2. In Blender: Edit → Preferences → Add-ons → Install from Disk… → select the zip.

3. Enable Interface: Blender MCP Bridge.

4. Open the 3D Viewport sidebar (N) → MCP Bridge tab → click Start Server.

The server listens on 127.0.0.1:9876. Blender must stay open while you use it.

2. Install the MCP server

cd blender-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python server/blender_mcp_server.py   # sanity check: should start without errors

3. Point your AI client at it

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/blender-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/blender-mcp/server/blender_mcp_server.py"]
    }
  }
}

Cursor: Settings → MCP → Add Server → same command/args.

Muse CLI: Muse mcp add blender -- /absolute/path/to/.venv/bin/python /absolute/path/to/server/blender_mcp_server.py

Then ask your assistant to ping_blender — if it answers with your Blender version, you're live.

Tools

Transports: stdio (default) or HTTP

By default the server speaks MCP over stdio — what Claude Desktop, Cursor, and Muse CLI expect (see config above).

For setups where one server should be shared (multiple local clients without spawning a process each, or remote access via a tunnel), run it over Streamable HTTP instead:

python server/blender_mcp_server.py --http --port 8000
# serves MCP at http://127.0.0.1:8000/mcp

Point any Streamable-HTTP-capable client at that URL. Keep it on localhost unless you know what you're doing — the bridge executes arbitrary Python.

Protocol (v1)

TCP on 127.0.0.1:9876. Every message = 4-byte big-endian length + UTF-8 JSON.

• Request: {"id": str, "command": str, "params": dict}

• Response: {"id": str, "ok": bool, "result": any, "error": str | null}

Commands are queued and executed on Blender's main thread via bpy.app.timers (bpy is not thread-safe), then the response is written back on the same socket.

Multiple AI clients

Yes — connect as many as you like. Each AI client (Claude Desktop, Cursor, Muse CLI, …) spawns its own copy of the MCP server, and the Blender add-on accepts simultaneous connections from all of them. Commands are serialized through Blender's main thread, so concurrent clients interleave safely instead of corrupting the scene. The sidebar panel shows how many clients are currently connected.

One tip: two AIs editing the same scene will step on each other's toes creatively (both creating "Cube", etc.). It works, but give them different tasks — or different .blend files — for the smoothest experience.

Troubleshooting

• "cannot reach Blender on 127.0.0.1:9876" → Blender isn't open, the add-on isn't enabled, or you didn't click Start Server.

• Port already in use → another Blender (or a zombie process) holds 9876. Close it or restart Blender.

• Screenshot fails → needs a visible 3D viewport; won't work in pure background (-b) mode.

Security

The add-on executes arbitrary Python sent over localhost. That is its job — but only run it on machines you trust, and never forward port 9876 to a network.

Project layout

addon/blender_mcp_bridge.py   # the Blender add-on (socket server + UI panel)
server/blender_mcp_server.py   # the MCP server (FastMCP tools over stdio)
server/bridge_client.py        # shared TCP client for the wire protocol
tests/                         # protocol + threading tests (no Blender needed)
dist/blender_mcp_bridge.zip    # installable add-on package