# Blender MCP Server
A high-performance MCP (Model Context Protocol) server for controlling Blender 3D from AI agents like Claude Code.
Built with Rust + PyO3 for native Python integration.
## Features
- **27 MCP tools** for scene manipulation, materials, modifiers, animation, rendering
- **HTTP transport** - works with any MCP client
- **Native Blender addon** with GUI controls
- **Thread-safe** architecture using channels
- **`execute_python`** escape hatch for arbitrary bpy code
## Quick Start
### 1. Install the wheel to Blender Python
```powershell
# Build
cd C:\projects\projects.rust\_mcp\blender-mcp-rs
maturin build --release
# Install to Blender 5.0
& "C:\Programs\Blender5\5.0\python\bin\python.exe" -m pip install target\wheels\blender_mcp-0.1.0-cp311-cp311-win_amd64.whl --force-reinstall
```
### 2. Enable the addon in Blender
The addon is symlinked to Blender's addons folder. Enable it in:
`Edit > Preferences > Add-ons > Search "MCP Server"`
Or via Python console:
```python
import bpy
bpy.ops.preferences.addon_enable(module="mcp_server")
```
### 3. Start the server
**Via GUI:** `Topbar > MCP > Start Server`
**Via Python:**
```python
bpy.ops.mcp.start(port=8765)
```
### 4. Connect Claude Code
Add to your MCP settings:
```json
{
"mcpServers": {
"blender": {
"url": "http://127.0.0.1:8765/mcp"
}
}
}
```
## Available Tools
### Scene & Objects
| Tool | Description |
|------|-------------|
| `scene_info` | Get scene metadata (name, fps, frame range, resolution) |
| `list_objects` | List objects with optional type/collection filter |
| `get_object` | Get object details (transform, type, mesh data) |
| `create_primitive` | Create mesh: cube, sphere, cylinder, plane, cone, torus |
| `update_object` | Set location, rotation, scale |
| `delete_object` | Remove object from scene |
| `duplicate_object` | Copy object with offset, optional linked |
### Selection & Hierarchy
| Tool | Description |
|------|-------------|
| `get_selection` | Get selected objects and active object |
| `set_selection` | Select objects by name |
| `parent_objects` | Set parent-child relationships |
| `get_collections` | Get collection hierarchy |
| `move_to_collection` | Move object to collection |
### Materials
| Tool | Description |
|------|-------------|
| `list_materials` | List all materials |
| `create_material` | Create Principled BSDF material |
| `assign_material` | Assign material to object |
### Modifiers
| Tool | Description |
|------|-------------|
| `get_modifiers` | List modifiers on object |
| `add_modifier` | Add SUBSURF, MIRROR, ARRAY, BEVEL, BOOLEAN, etc. |
| `apply_modifier` | Apply modifier permanently |
### Animation
| Tool | Description |
|------|-------------|
| `set_keyframe` | Insert keyframe on property |
### I/O & Rendering
| Tool | Description |
|------|-------------|
| `render_image` | Render to file (CYCLES/EEVEE) |
| `export_scene` | Export FBX, OBJ, GLTF, USD |
| `import_file` | Import 3D files |
| `save_file` | Save .blend file |
### Utility
| Tool | Description |
|------|-------------|
| `set_mode` | OBJECT, EDIT, SCULPT, VERTEX_PAINT, etc. |
| `undo` | Undo last action |
| `redo` | Redo |
| `execute_python` | Run arbitrary bpy code |
## Architecture
```
Claude Code <--HTTP--> BlenderMcp (Rust) <--Channel--> Python Polling
(MCP + axum) (bpy.app.timers)
|
v
Blender Python (bpy)
```
- **Rust thread** runs tokio + axum HTTP server
- **Crossbeam channels** pass commands/responses
- **Python timer** polls for commands, executes bpy, returns results
- **Graceful shutdown** - no hangs on stop
## Development
### Build
```powershell
# Debug
maturin develop
# Release
maturin build --release
```
### Test
```powershell
# Standalone Python
& "C:\Programs\Blender5\5.0\python\bin\python.exe" -c "import blender_mcp; print(dir(blender_mcp))"
# Blender background
& "C:\Programs\Blender5\blender.exe" --background --python python\test_addon_server.py
```
### Project Structure
```
blender-mcp-rs/
├── src/
│ ├── lib.rs # PyO3 module, BlenderMcp class
│ ├── server.rs # MCP server, tool definitions
│ ├── protocol.rs # Command/Response types
│ └── error.rs # Error handling
├── addon/
│ └── mcp_server/ # Blender addon (symlinked)
│ └── __init__.py
├── python/
│ └── test_*.py # Test scripts
├── Cargo.toml
└── pyproject.toml
```
## Requirements
- Blender 4.0+ (tested on 5.0)
- Rust 1.70+
- Python 3.11 (Blender's bundled)
- maturin
## License
MIT