# Blender MCP Ultra

> **205 tools. 37 modules. Complete Blender control via MCP.**

A production-grade Model Context Protocol (MCP) server that gives AI agents full control of Blender. Create, animate, light, render, and sculpt — all through structured tools, no scripts needed.

## Features

- **205 structured tools** across 37 modules — every tool does one thing well
- **Zero `execute_blender_code` needed** for most workflows — structured tools are faster, safer, and save tokens
- **Wizard tools** — one call creates a complete scene (product shots, interiors, characters, environments)
- **Batch tools** — operate on hundreds of objects in a single call
- **Works with any LLM** — optimized for weak models (GPT-3.5, Haiku, Flash) via compact tool grouping
- **Blender 5.2+ compatible** — tested with EEVEE Next and Cycles

## Installation

### MCP Server (for AI agents)

```bash
pip install blender-mcp-ultra
# or with uv
uv pip install blender-mcp-ultra
```

### Blender Addon

```bash
# Deploy addon to Blender
python deploy.py
# or manually copy addon/ to your Blender scripts/addons directory
```

Enable the addon in Blender Preferences → Add-ons → search "Blender MCP Ultra".

## Quick Start

```python
# From your MCP client (opencode, Claude, etc.)
from blender_mcp_ultra import BlenderMCPServer

server = BlenderMCPServer()
server.connect()  # Auto-starts Blender addon on port 9876

# Create a product shot in one call
server.call("wizard_product_shot", {
    "product_type": "sphere",
    "product_color": [0.8, 0.2, 0.2],
    "render": True,
    "samples": 32
})

# Or build scenes tool-by-tool
server.call("create_object", {"object_type": "MESH", "name": "MyMesh"})
server.call("create_material", {"name": "RedMetal", "color": [0.8, 0.1, 0.1], "metallic": 0.9})
server.call("assign_material", {"object_name": "MyMesh", "material_name": "RedMetal"})
server.call("setup_studio_3point", {"key_energy": 18, "fill_energy": 8, "rim_energy": 35})
server.call("create_turntable_animation", {"object_name": "MyMesh", "frames": 250})
server.call("render_image", {"samples": 64})
```

## Tool Groups

Grouped tools save tokens by doing one specific job well. Each group is independent — animation tools don't import sculpting, material tools don't import physics.

| Group | Tools | Use For |
|-------|-------|---------|
| **Turntable** | `create_turntable_animation`, `set_animation_cyclic`, `set_bezier_easing` | Rotation animations |
| **Studio Camera** | `setup_studio_camera`, `set_camera_framing` | Camera for any subject |
| **Studio Lighting** | `setup_studio_3point`, `set_studio_world`, `create_studio_floor` | 3-point lighting |
| **Material Config** | `configure_display_material`, `configure_glass_material`, `configure_body_material`, `reassign_material_slot` | Screen/glass/body materials |
| **Constraints** | `add_object_constraint`, `remove_object_constraint` | Object constraints (27 types) |
| **Shape Keys** | `add_shape_key`, `set_shape_key_value`, `remove_shape_key` | Morph targets |
| **NLA** | `add_nla_track`, `add_nla_strip` | Non-linear animation |
| **Markers** | `add_marker`, `remove_marker` | Timeline markers |
| **Vertex Colors** | `add_color_attribute`, `set_vertex_color` | Per-vertex color data |
| **Custom Properties** | `set_custom_property`, `get_custom_property` | User-defined metadata |
| **World/Compositor** | `setup_world_sky_texture`, `setup_compositor` | Sky textures, post-processing |
| **Lattice/Paint** | `create_lattice`, `apply_lattice_deform`, `enter_weight_paint`, `enter_vertex_paint` | Deformation, painting |
| **Library/Normals** | `link_blend_data`, `set_custom_normals` | External assets, custom normals |
| **Batch** | `batch_create_objects`, `batch_rename`, `batch_select`, `batch_transform`, `batch_material_preset` | Multiple objects |
| **Wizard** | `wizard_product_shot`, `wizard_archviz_interior`, etc. | Complete scenes |

## All 205 Commands by Domain

### Objects (11)
`create_object` `delete_object` `duplicate_object` `join_objects` `parent_objects` `rename_object` `select_objects` `set_object_visibility` `set_origin` `shade_object` `convert_object`

### Transforms (8)
`move_object` `rotate_object` `scale_object` `set_object_transform` `get_local_transforms` `align_object` `apply_transform` `snap_to_cursor`

### Modifiers (14)
`add_modifier` `remove_modifier` `apply_modifier` `configure_modifier` `reorder_modifier` `bevel_edges` `boolean_operation` `extrude_faces` `inset_faces` `loop_cut` `merge_vertices` `subdivide_mesh` `flip_normals` `recalculate_normals`

### Mesh Editing (10)
`edit_mesh_vertices` `edit_mesh_edges` `edit_mesh_faces` `create_vertex_group` `assign_vertex_group` `smooth_vertices` `tri_to_quad` `limited_dissolve` `separate_by_loose` `separate_by_material`

### Mesh Quality (5)
`analyze_mesh_quality` `get_mesh_statistics` `check_production_readiness` `find_duplicates` `fix_mesh_defects`

### Materials (10)
`create_material` `delete_material` `assign_material` `set_material_property` `create_procedural_material` `add_shader_node` `set_shader_node_value` `connect_shader_nodes` `apply_image_texture` `list_materials`

### Material Config (4)
`configure_display_material` `configure_glass_material` `configure_body_material` `reassign_material_slot`

### Lights (5)
`create_light` `configure_light` `setup_hdri_lighting` `setup_studio_lighting` `list_lights`

### Studio Lighting (3)
`setup_studio_3point` `set_studio_world` `create_studio_floor`

### Camera (5)
`create_camera` `configure_camera` `setup_camera_track_to` `setup_turntable_camera` `set_camera_to_view`

### Studio Camera (2)
`setup_studio_camera` `set_camera_framing`

### Animation (8)
`set_keyframe` `delete_keyframe` `set_interpolation` `set_animation_range` `set_fps` `go_to_frame` `create_walk_cycle` `setup_subdivision_animation`

### Turntable (3)
`create_turntable_animation` `set_animation_cyclic` `set_bezier_easing`

### Constraints (2)
`add_object_constraint` `remove_object_constraint`

### Shape Keys (3)
`add_shape_key` `set_shape_key_value` `remove_shape_key`

### NLA (2)
`add_nla_track` `add_nla_strip`

### Markers (2)
`add_marker` `remove_marker`

### Vertex Colors (2)
`add_color_attribute` `set_vertex_color`

### Custom Properties (2)
`set_custom_property` `get_custom_property`

### World & Compositor (2)
`setup_world_sky_texture` `setup_compositor`

### Lattice (2)
`create_lattice` `apply_lattice_deform`

### Weight/Vertex Paint (2)
`enter_weight_paint` `enter_vertex_paint`

### Library & Normals (2)
`link_blend_data` `set_custom_normals`

### Scene (5)
`get_scene_info` `list_objects` `get_object_info` `create_scene` `set_scene_property`

### Viewport (4)
`get_viewport_info` `set_viewport_shading` `set_viewport_camera` `toggle_overlays`

### Viewport Enhanced (3)
`get_viewport_screenshot` `get_viewport_screenshot_comparison` `get_render_preview`

### Sculpting (6)
`configure_sculpt_brush` `enter_sculpt_mode` `exit_sculpt_mode` `set_sculpt_symmetry` `configure_dyntopo` `remesh_sculpt`

### UV (6)
`uv_smart_project` `uv_unwrap` `uv_pack_islands` `uv_project_from_view` `uv_select_island` `get_uv_info`

### Physics (7)
`add_rigid_body` `add_cloth_physics` `add_fluid_physics` `add_particle_system` `add_force_field` `bake_physics` `delete_physics`

### Geometry Nodes (4)
`add_geometry_nodes_modifier` `add_geometry_node` `connect_geometry_nodes` `create_procedural_distribution`

### Curves (5)
`create_curve` `create_text_object` `edit_curve_points` `set_curve_fill` `convert_curve_to_mesh`

### Armature (6)
`create_armature` `add_bone` `create_humanoid_rig` `add_bone_constraint` `setup_ik_chain` `parent_bone_to_object`

### Collections (5)
`create_collection` `delete_collection` `move_to_collection` `set_collection_visibility` `list_collections`

### File I/O (5)
`import_file` `export_file` `export_fbx` `export_glb` `export_obj`

### Procedural (4)
`create_terrain` `create_tree` `create_rock` `create_particle_field`

### Batch (11)
`batch_create_objects` `batch_delete_objects` `batch_transform` `batch_add_modifiers` `batch_material_preset` `batch_rename` `batch_parent` `batch_visibility` `batch_select` `batch_set_origin` `execute_sequence`

### Rendering (4)
`render_image` `render_animation` `render_preview` `configure_render`

### Multi-Scene (8)
`list_open_scenes` `open_blend_file` `save_blend_file` `new_scene` `switch_scene` `delete_scene` `merge_blend_file` `get_scene_diff`

### Code Execution (2)
`execute_blender_code` `run_operator`

### Wizards (11)
`wizard_product_shot` `wizard_archviz_interior` `wizard_character_basemesh` `wizard_environment` `wizard_studio_render` `wizard_uv_unwrap_all` `wizard_scene_optimize` `wizard_material_preset` `wizard_quick_scene` `wizard_turntable` `wizard_batch_materials`

## Architecture

```
opencode ──MCP stdio──▶ blender_mcp_ultra.server ──WebSocket 9876──▶ Blender addon
```

1. AI agent calls MCP tool via stdio
2. MCP server serializes command and sends via WebSocket to Blender
3. Blender addon queues command on main thread
4. Handler executes the Blender API call
5. Result returned through the same path

## Development

```bash
# Install dependencies
pip install -e ".[dev]"

# Run MCP server (standalone test)
blender-mcp-ultra

# Run Blender with addon
blender --python blender_startup.py

# Run tests
pytest tests/

# Lint
ruff check src/
```

## License

MIT