# BlenderCopilot

**Forge 3D worlds with AI.** An MCP server for Blender.

Inspired by [blender-mcp](https://github.com/ahujasid/blender-mcp). BlenderCopilot gives any MCP-compatible AI full control over Blender's 3D pipeline — object creation, mesh operations, materials, rigging, animation, physics, baking, node graphs, camera, rendering, and asset integrations. Works with Claude, Claude Code, Cursor, VS Code, Windsurf, and any MCP client.

## Features

- **55 structured tools** across every domain: objects, mesh, materials, UV, baking, rigging, animation, physics, nodes, camera, rendering, LOD, volumes
- **Action-based design** — fewer tools, more actions per tool. Optimized for AI tool discovery
- **Universal Node Graph Engine** — geometry nodes, shader nodes, and compositor through one tool
- **Visual feedback loop** — `analyze_scene` returns viewport screenshot + structured metadata
- **5 asset integrations** — Poly Haven, Sketchfab, Hyper3D Rodin, Hunyuan3D, Trellis2
- **Auto-screenshot** — opt-in to get viewport screenshots after every modifying command
- **Blender 4.2+ native** — extension format with proper permission declarations

## Architecture

```
Any MCP Client (Claude, Cursor, VS Code, etc.)
        ↓ MCP Protocol (stdio)
BlenderCopilot MCP Server    ← pip install / uvx
        ↓ JSON over TCP Socket
BlenderCopilot Addon         ← installed in Blender
        ↓ bpy API
Blender
```

## Installation

### 1. MCP Server

**Claude Code:**
```bash
claude mcp add blender-copilot -- uvx blender-copilot
```

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

**Cursor / VS Code / Windsurf** — same JSON in your MCP settings.

### 2. Blender Addon

Requires **Blender 4.2+**.

1. Download the latest `blender_copilot.zip` from [Releases](../../releases), or build it yourself:
   ```bash
   cd addon && zip -r ../blender_copilot.zip . -x '*.pyc' '__pycache__/*'
   ```
2. In Blender: **Edit > Preferences > Extensions**
3. Click the dropdown arrow next to "Repositories" → **Install from Disk**
4. Select the `blender_copilot.zip` file
5. Enable **"Blender Copilot"** if not already enabled

**For development** (changes apply instantly without reinstalling):
```bash
# macOS — Blender 5.0+
ln -s /path/to/blender-copilot/addon "$HOME/Library/Application Support/Blender/5.0/extensions/user_default/blender_copilot"

# Linux — Blender 5.0+
ln -s /path/to/blender-copilot/addon ~/.config/blender/5.0/extensions/user_default/blender_copilot

# Windows — Blender 5.0+ (run as admin)
mklink /D "%APPDATA%\Blender Foundation\Blender\5.0\extensions\user_default\blender_copilot" C:\path\to\blender-copilot\addon
```

### 3. Connect

1. In Blender's 3D View sidebar (press **N**), find the **BlenderCopilot** tab
2. Enable the integrations you want (expand Poly Haven, Sketchfab, etc.)
3. Click **Start MCP Server**
4. Start talking to your AI

## Tool Catalog (55 tools)

### Object Management
| Tool | What it does |
|------|-------------|
| `create_object` | Create meshes (cube, sphere, cylinder, plane, cone, torus), lights, cameras, empties |
| `transform_object` | Move, rotate, scale — absolute or delta mode |
| `duplicate_object` | Copy objects, optionally linked (shared mesh data) |
| `delete_object` | Remove objects by name list |

### Mesh Operations
| Tool | What it does |
|------|-------------|
| `mesh_operation` | Join, separate, boolean (union/difference/intersect), shade smooth/flat, apply transforms, set origin, voxel remesh |
| `generate_lod_chain` | Create LOD levels with automatic decimation |
| `generate_collision_mesh` | Generate collision meshes (convex hull, box, voxel) |

### Materials
| Tool | What it does |
|------|-------------|
| `manage_materials` | Create PBR materials, assign to objects, list, set base color/metallic/roughness |

### UV Mapping
| Tool | What it does |
|------|-------------|
| `uv_operation` | Smart UV project, lightmap pack, unwrap, create/set/list UV layers |

### Texture Baking
| Tool | What it does |
|------|-------------|
| `bake_textures` | Bake high→low poly textures: diffuse, normal, AO, roughness, combined, emit |

### Node Graph Engine
| Tool | What it does |
|------|-------------|
| `build_node_graph` | Create/replace geometry nodes, shader nodes, or compositor nodes |
| `get_node_graph` | Read back any node tree as structured JSON |
| `list_node_types` | Discover available nodes by category |

### Modifiers
| Tool | What it does |
|------|-------------|
| `modify_object` | Add, remove, apply, or configure any modifier (subsurf, bevel, array, mirror, boolean, solidify, etc.) |

### Rigging
| Tool | What it does |
|------|-------------|
| `manage_armature` | Create armatures, add/modify bones, parent meshes with auto weights, IK, bone constraints |
| `manage_weights` | Vertex group assignment, auto weights, normalize, list, remove |
| `manage_shape_keys` | Blend shapes / morph targets — add, set value, keyframe, list, remove |

### Animation
| Tool | What it does |
|------|-------------|
| `set_keyframe` | Keyframe location/rotation/scale/custom properties with interpolation control |
| `manage_actions` | Create, assign, list, duplicate animation actions |
| `manage_nla` | NLA tracks and strips for non-linear animation layering |

### Physics & Constraints
| Tool | What it does |
|------|-------------|
| `manage_physics` | Rigid body, collision, cloth, soft body — add, remove, configure |
| `manage_constraints` | Object constraints: Track To, Copy Rotation, Limit Location, Child Of, etc. |

### Camera & Rendering
| Tool | What it does |
|------|-------------|
| `set_camera` | Focal length, sensor, DOF, focus object/distance |
| `render_scene` | Render to file — engine, samples, resolution, format, denoising |
| `set_viewport_shading` | Set viewport mode: wireframe, solid, material, rendered |
| `configure_render_settings` | Engine, samples, resolution, color management, world color, EEVEE features |

### Scene & Inspection
| Tool | What it does |
|------|-------------|
| `get_scene_info` | Scene overview — objects, materials, render engine |
| `get_object_info` | Object details — transform, mesh data, world bounding box |
| `get_viewport_screenshot` | Capture the 3D viewport as PNG |
| `execute_blender_code` | Run arbitrary Python in Blender (fallback for anything not covered) |
| `analyze_scene` | Screenshot + structured metadata for visual feedback loops |
| `manage_collections` | Create, delete, nest collections; move objects; purge orphans |
| `import_model` | Import GLB, FBX, OBJ, USD, STL, ABC, PLY, DAE |
| `export_model` | Export scene or selection to any format |

### Volume Grids (Blender 5.0+)
| Tool | What it does |
|------|-------------|
| `volume_operation` | Mesh↔SDF conversion, SDF boolean/offset/fillet/smooth, procedural terrain |

### Asset Integrations
| Tool | What it does |
|------|-------------|
| `get_polyhaven_status` | Check Poly Haven integration status |
| `get_polyhaven_categories` | List Poly Haven asset categories |
| `search_polyhaven_assets` | Search HDRIs, textures, models |
| `download_polyhaven_asset` | Download and import Poly Haven assets |
| `set_texture` | Apply Poly Haven PBR texture to object |
| `get_sketchfab_status` | Check Sketchfab integration status |
| `search_sketchfab_models` | Search Sketchfab model library |
| `get_sketchfab_model_preview` | Preview model thumbnail before downloading |
| `download_sketchfab_model` | Download with automatic size normalization |
| `get_hyper3d_status` | Check Hyper3D Rodin status |
| `generate_hyper3d_model_via_text` | Text-to-3D via Hyper3D Rodin |
| `generate_hyper3d_model_via_images` | Image-to-3D via Hyper3D Rodin |
| `poll_rodin_job_status` | Poll Hyper3D generation progress |
| `import_generated_asset` | Import completed Hyper3D model |
| `get_hunyuan3d_status` | Check Hunyuan3D status |
| `generate_hunyuan3d_model` | Text/image-to-3D via Hunyuan3D |
| `poll_hunyuan_job_status` | Poll Hunyuan3D generation progress |
| `import_generated_asset_hunyuan` | Import completed Hunyuan3D model |
| `get_trellis2_status` | Check Trellis2 status |
| `generate_trellis2_model` | Image-to-3D via local Trellis2 |

## Example Workflows

**Scene building:**
> "Create a cube, scale it to [2, 0.1, 3] for a wall, duplicate it 3 times, position them as a room, add a sun light, set viewport to rendered"

**Material design:**
> "Create a red metallic material with roughness 0.2, assign it to the cube, then build a noise-based bump shader node graph"

**Game-ready pipeline:**
> "UV unwrap the model, generate LOD chain at 50%/25%/10%, create convex hull collision mesh, bake normal and AO maps at 2K, export as GLB"

**Character rigging:**
> "Create an armature with spine, chest, neck, head bones. Parent the mesh with auto weights. Add IK to the arms."

**Physics simulation:**
> "Add rigid body to all objects in the scene. Set the floor as collision. Set mass to 5kg on the sphere."

## Environment Variables

```bash
export BLENDER_HOST='localhost'   # default
export BLENDER_PORT=9876          # default
```

## Troubleshooting

- **Connection issues** — make sure the addon is running before using AI tools
- **Timeout errors** — break complex operations into smaller steps
- **First command fails** — normal on cold start, retry and it works
- **Restart both** — if things break, restart both the AI client and the addon

## Contributing

Contributions welcome. See [TESTING.md](TESTING.md) for the test plan.

## License

MIT — Pedro Augusto
