blender-copilot 1.0.0

Forge 3D worlds with AI — the MCP server for Blender

BlenderCopilot

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

Inspired by 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:

claude mcp add blender-copilot -- uvx blender-copilot

Claude Desktop — edit claude_desktop_config.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, or build it yourself:

   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):

# 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

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 for the test plan.

License

MIT — Pedro Augusto