# 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