# 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

```powershell
# 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`](docs/tools_reference.md) for the full schema
and examples.

---

## Development

```powershell
# 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`](LICENSE).