Blender MCP — MiniMax Connector for Blender 5.2 LTS

A Model Context Protocol bridge that lets MiniMax Code (and any MCP client) drive Blender 5.2 LTS through natural language. Ships as two artifacts:

Artifact	What it is	Where it lives
Blender add-on	Python add-on that runs an MCP Streamable-HTTP server inside Blender on a background thread	addon/blender_mcp_addon/ → installed into Blender
MiniMax Plugin V1	Local MiniMax Code plugin that connects to the running Blender MCP server and exposes its tools to the agent	connector/ → installed into C:/Users/.../.minimax/plugins/blender-mcp/

The Blender add-on is the source of truth for Blender-side state. The MiniMax plugin is a thin client that calls the add-on's HTTP endpoint — no Python process is spawned on the MiniMax side, so there's no port-leak or lifecycle mess.

---

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 any modern MCP client (MiniMax Code, Claude Desktop, Cursor) and survives Blender restarts.
• 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.
• MiniMax Plugin V1 with streamable-http capability — the plugin doesn't spawn anything; it just points at the Blender add-on's endpoint.

---

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.py         ← AddOnPreferences (port, auth token, autostart)
│       ├── 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
├── connector/                     ← MiniMax Plugin V1 source
│   ├── .minimax-plugin/
│   │   └── plugin.json
│   ├── servers/
│   │   └── blender.mcp.json       ← streamable-http → http://127.0.0.1:8765/mcp
│   ├── icon.png                   ← category icon (Design / 3D)
│   └── README.md
├── scripts/
│   ├── install_addon.ps1          ← zip and install into Blender
│   └── install_connector.ps1      ← copy connector into ~/.minimax/plugins/
├── examples/
│   ├── basic_scene.md
│   ├── material_setup.md
│   └── render_workflow.md
└── docs/
    ├── architecture.md
    ├── blender_5_2_notes.md
    └── tools_reference.md

---

Quickstart

# 1. Clone the repository
git clone https://github.com/tattooinmtl/Minimax_Blender_MCP.git
cd Minimax_Blender_MCP

# 2. Install the Blender add-on
pwsh ./scripts/install_addon.ps1

# 3. Install the MiniMax connector plugin
pwsh ./scripts/install_connector.ps1

4. Enable in Blender

1. Open Blender.
2. Go to Edit → Preferences → Add-ons.
3. Search for "Blender MCP" and check the box to enable it.
4. Set the port (default 8765) and click Start Server (or start it from the 3D Viewport sidebar under the Blender MCP tab).
5. You will see [Blender MCP] Server listening on http://127.0.0.1:8765/mcp in the console.

3. Verify

In a MiniMax Code chat, ask:

Use the blender connector: list the first 5 objects in the current scene.

You should see the agent call tools/list against your running Blender.

---

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

The MiniMax plugin also ships a Skill (blender-mcp-quickstart) that gives the agent an at-a-glance tool index, safety rules, and common recipes. Read it before doing non-trivial work.

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.