# BlenderMCP — Blender Model Context Protocol Integration

BlenderMCP connects Blender to AI assistants through the Model Context Protocol (MCP), letting Claude directly control Blender for prompt-assisted 3D modelling, scene creation, rendering, and automation.

This is an extended fork of [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) with **92 tools**, full Blender 4.x compatibility, and telemetry removed.

---

## What's new in this fork

- **92 tools** across 26 categories (up from the original ~20)
- **Blender 4.x compatibility** — fixes for BMesh layer API changes, EEVEE engine name, `temp_override` region requirement, compositor node ordering
- **No telemetry** — all analytics code removed
- **Auto-restart on addon reload** — server restarts automatically when the addon is cycled in Preferences; no manual click needed
- **`img_to_3d_server.py`** — local image-to-3D inference via TripoSR (optional, loads/unloads on demand to free VRAM)
- **`TOOLS.md`** — full reference for all 92 tools with parameters

---

## Tool categories (92 tools)

| Category | Tools |
|---|---|
| Process management | `start_blender`, `close_blender`, `get_blender_status` |
| Scene & object info | `get_scene_info`, `get_object_info`, `find_objects_by_type`, `measure_distance` |
| Primitives & object mgmt | `add_primitive`, `delete_object`, `duplicate_object`, `rename_object`, `join_objects`, `separate_mesh`, `set_origin`, `snap_to_ground`, `set_smooth_shading`, `parent_object`, `select_objects`, `align_objects` |
| Transforms | `move_object`, `scale_object`, `rotate_object` |
| Mesh editing | `get_mesh_stats`, `subdivide_mesh`, `apply_modifier`, `set_vertex_position` |
| Vertex operations | `get_vertex_positions`, `set_vertex_positions` |
| Edge operations | `get_edges`, `mark_sharp_edges`, `set_edge_crease`, `set_edge_bevel_weight` |
| Face operations | `get_faces`, `extrude_faces`, `inset_faces`, `flip_normals`, `merge_vertices`, `triangulate_mesh`, `set_face_material_index` |
| Curve control points | `get_control_points`, `set_control_point` |
| Camera | `create_camera`, `set_active_camera` |
| Lighting | `add_light`, `set_world_background`, `add_3point_lighting` |
| Materials | `create_material`, `assign_material`, `set_object_material_color`, `load_texture`, `set_texture` |
| Modifiers | `add_modifier`, `boolean_operation` |
| Rendering | `set_render_settings`, `render_from_camera`, `render_all_cameras` |
| Viewport capture | `get_viewport_screenshot`, `capture_viewport_angle`, `capture_contact_sheet`, `render_depth_map` |
| Reference images | `store_reference_image`, `compare_reference_image`, `diff_images` |
| Animation | `add_keyframe`, `set_frame` |
| Collections | `create_collection`, `move_to_collection` |
| Export / import | `export_object`, `import_file`, `save_blend`, `load_blend` |
| Scripting | `execute_blender_code` |
| PolyHaven | `get_polyhaven_status`, `get_polyhaven_categories`, `search_polyhaven_assets`, `download_polyhaven_asset` |
| Sketchfab | `get_sketchfab_status`, `search_sketchfab_models`, `get_sketchfab_model_preview`, `download_sketchfab_model` |
| Hyper3D / Rodin | `get_hyper3d_status`, `generate_hyper3d_model_via_text`, `generate_hyper3d_model_via_images`, `poll_rodin_job_status`, `import_generated_asset` |
| Hunyuan3D | `get_hunyuan3d_status`, `generate_hunyuan3d_model`, `poll_hunyuan_job_status`, `import_generated_asset_hunyuan` |
| Image-to-3D (TripoSR) | `load_img_to_3d_model`, `generate_3d_from_image`, `unload_img_to_3d_model` |

See [TOOLS.md](TOOLS.md) for full parameter documentation.

---

## Requirements

- Blender 4.0 or newer (Blender 4.3 recommended)
- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager

---

## Installation

### 1. Install the MCP server

```bash
git clone https://github.com/naab007/blender_mcp
cd blender_mcp
uv venv .venv
uv pip install -e .
```

### 2. Install the Blender addon

1. Download `addon.py` from this repo
2. Open Blender → Edit → Preferences → Add-ons → Install...
3. Select `addon.py` and enable **Interface: Blender MCP**
4. In the 3D View sidebar (N), open the **BlenderMCP** tab and click **Start MCP Server**

> To update after the first install, copy the new `addon.py` over the installed one
> (`<Blender config>/scripts/addons/addon.py`) and cycle the add-on off/on in
> Preferences — the MCP server restarts automatically.

### 3. Configure your AI client

**Claude Code** — create `.mcp.json` in your working directory:
```json
{
  "mcpServers": {
    "blender": {
      "type": "stdio",
      "command": "/path/to/blender_mcp/.venv/Scripts/blender-mcp.exe"
    }
  }
}
```

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}
```

**Cursor** — add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}
```

---

## Usage

Once the addon is running and the MCP server is configured, ask Claude to:

- "Create a low-poly dungeon scene with a dragon guarding a pot of gold"
- "Set up 3-point studio lighting and render from the active camera"
- "Add a Subdivision Surface modifier to the selected object and apply a PBR material"
- "Capture viewport angles from front, side, and top and give me a contact sheet"
- "Boolean-subtract the sphere from the cube"
- "Download a rock model from PolyHaven and place it at the origin"
- "Generate a 3D model of a garden gnome via Hyper3D"
- "Render depth map of the current scene"
- "Keyframe this object moving from (0,0,0) to (5,0,0) over 60 frames"
- "Compare these two renders and show me exactly what changed" → `diff_images(path_a, path_b)`

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `BLENDER_HOST` | `localhost` | Host for the Blender TCP socket |
| `BLENDER_PORT` | `9876` | Port for the Blender TCP socket |
| `IMG_TO_3D_PORT` | `7862` | Port for the local TripoSR server |
| `IMG_TO_3D_MODEL_DIR` | `stabilityai/TripoSR` | Local weights path or HuggingFace hub ID |
| `IMG_TO_3D_DEVICE` | auto | `cuda` or `cpu` |

## Dependencies

| Package | Version | Purpose |
|---|---|---|
| `mcp[cli]` | ≥1.3.0 | MCP server framework |
| `pillow` | ≥10.0.0 | Image processing (viewport capture, contact sheets, diff) |
| `numpy` | ≥1.24.0 | Pixel math for `diff_images` |
| `flask` | ≥3.0.0 | Local TripoSR inference server |
| `requests` | ≥2.31.0 | PolyHaven / Sketchfab / Hyper3D API calls |

---

## Architecture

```
Claude / AI client
      │  MCP (stdio)
      ▼
server.py  (FastMCP, @mcp.tool functions)
      │  JSON over TCP :9876
      ▼
addon.py   (Blender Python addon, bpy.app.timers dispatch)
      │
      ▼
Blender scene
```

- All addon handlers run on Blender's main thread via `bpy.app.timers.register()` — no threading issues
- Commands are JSON `{ "type": "...", "params": {...} }`, responses are `{ "status": "success"|"error", "result": ... }`

---

## Troubleshooting

- **"context is incorrect" on view3d operators** — requires Blender 4.x `temp_override(area=area, region=region)`. Already fixed in this fork.
- **BLENDER_EEVEE enum not found** — use `BLENDER_EEVEE_NEXT` in Blender 4.x. Already normalized in this fork.
- **Render writes nothing after depth map** — compositor state corruption from empty node tree. Fixed in this fork via full snapshot/restore in `render_depth_map`.
- **`execute_blender_code`** runs arbitrary Python in Blender — powerful but irreversible. Save your work first.
- **Connection issues** — ensure the addon server is running (green dot in the BlenderMCP sidebar tab) before sending commands.

---

## License

MIT — see [LICENSE](LICENSE).

Based on [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) by Siddharth Ahuja.