Blender MCP — Streamable-HTTP bridge for Blender 5.2 LTS

A Model Context Protocol bridge that lets any MCP client (Antigravity, Cursor, Claude Desktop, VS Code 1.101+, MiniMax Code, Windsurf, Continue, Cline, OpenCode, Codex, MCP Inspector, …) drive Blender 5.2 LTS through natural language.

The add-on runs an MCP Streamable-HTTP server inside Blender on a background thread. The client just points at it — no subprocess is spawned, no socket pair to babysit.

---

Why this shape

• Single install path inside Blender. The MCP server runs in-process using bpy, so there's no uvx/pipx dance and no socket pair to keep in sync.
• Streamable HTTP on localhost. Works with every modern MCP client.
• Hand-rolled MCP server in the add-on. Blender 5.2 LTS bundles Python 3.13 with no external packages by default. A ~300-line MCP server is more portable than dragging in mcp[cli] and editing sys.path.
• Client-agnostic. No proprietary plugin format. Any MCP client that can hit an HTTP endpoint (or a stdio proxy that does) works.

---

Project layout

blender_addon_mcp/
├── README.md                      ← you are here
├── LICENSE                        ← MIT
├── pyproject.toml                 ← dev tooling for the add-on (ruff, mypy, pytest)
├── .gitignore
├── addon/
│   └── blender_mcp_addon/         ← zips into a Blender-installable .zip
│       ├── __init__.py            ← bl_info, register/unregister, preferences
│       ├── server/
│       │   ├── __init__.py
│       │   ├── mcp_server.py      ← MCP protocol (initialize, tools/list, tools/call, ping)
│       │   ├── transport.py       ← stdlib http.server, runs on a daemon thread
│       │   └── protocol.py        ← JSON-RPC 2.0 + MCP 2025-03-26 types
│       ├── tools/
│       │   ├── __init__.py        ← tool registry
│       │   ├── scene.py           ← scene_info, frame control
│       │   ├── objects.py         ← list, get, create, delete, transform
│       │   ├── materials.py       ← create, assign, modify
│       │   ├── modifiers.py       ← add, set params, remove
│       │   ├── render.py          ← render_image, screenshot_viewport
│       │   └── code.py            ← execute_python (with confirmation)
│       └── utils/
│           ├── __init__.py
│           ├── bpy_helpers.py     ← bpy → JSON serialization
│           └── safe_eval.py       ← ast-validated code execution
├── scripts/
│   ├── install_addon.ps1          ← zip and install into Blender
│   ├── blender_mcp_proxy.js       ← optional stdio/socket ↔ HTTP bridge for
│   │                                Antigravity builds that don't accept `url`
│   └── start_blender_mcp_bridge.ps1  ← start/stop/status lifecycle for the bridge
├── examples/
│   ├── mcp-configs.md             ← copy-paste configs for every major MCP client
│   ├── basic_scene.md
│   ├── material_setup.md
│   └── render_workflow.md
└── docs/
    ├── architecture.md
    ├── blender_5_2_notes.md
    └── tools_reference.md

---

Quickstart

1. Install the add-on

# clone
git clone https://github.com/tattooinmtl/Blender_MCP.git
cd Blender_MCP

# install the add-on into every Blender version on this machine
pwsh ./scripts/install_addon.ps1

2. Enable the server in Blender

1. Open Blender.
2. Edit → Preferences → Add-ons → search "Blender MCP" → check the box.
3. Set the port (default 8765) and click Start Server (or use the Blender MCP panel in the 3D Viewport sidebar).
4. The console should print:

   [Blender MCP] Server listening on http://127.0.0.1:8765/mcp
   

3. Wire up your MCP client

Pick the client you use and paste the matching snippet from examples/mcp-configs.md. The Antigravity url form is the simplest:

{
  "mcpServers": {
    "blender": { "url": "http://127.0.0.1:8765/mcp" }
  }
}

Snippets for Cursor, Claude Desktop, VS Code, MiniMax Code, Windsurf, Continue, Cline, and the MCP Inspector are all in that file.

4. Verify

In any MCP client chat:

Use the blender server: ping.

You should see the agent call tools/call on ping and report an empty successful result. From a terminal:

curl -s -X POST http://127.0.0.1:8765/mcp `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

---

Tools exposed

Tool	Purpose	Read-only
get_addon_info	Capability handshake — name, version, protocol, tools list. Call this first.	yes
scene_info	Scene summary (objects, lights, cameras, frame)	yes
list_objects	List scene objects, optional type filter	yes
get_object	Full object details (location, rotation, scale, modifiers, materials)	yes
create_object	Create primitive (cube, sphere, plane, cylinder, cone, torus, empty, camera, light)	no
delete_object	Delete an object by name	no
transform_object	Set location/rotation/scale	no
set_material	Create or assign a material with a Principled BSDF	no
set_texture	Apply an image file to a material input (base_color, roughness, normal, etc.)	no
import_asset	Import GLB/GLTF/FBX/OBJ/STL/PLY/DAE/USD/X3D/ABC	no
add_modifier	Add a modifier (subdivision, mirror, solidify, array, bevel)	no
remove_modifier	Remove a modifier by name	no
frame_get / frame_set	Read / move the timeline	mixed
render_image	Render the current frame to a file	no
screenshot_viewport	Capture the current viewport	no
execute_python	Run arbitrary bpy code (guarded by ast validation)	no
ping	Health check	yes

See docs/tools_reference.md for the full schema and examples.

---

Development

# syntax-check the add-on (Blender's Python is at <blender>/python/bin/python.exe)
python -m py_compile addon/blender_mcp_addon/__init__.py
python -m py_compile addon/blender_mcp_addon/server/mcp_server.py
# ...etc

# lint
ruff check addon/
mypy addon/

# test the MCP server in isolation (no bpy required)
pytest addon/tests/ -v

---

License

MIT. See LICENSE.