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

Mesh Operations

Materials

UV Mapping

Texture Baking

Node Graph Engine

Modifiers

Rigging

Animation

Physics & Constraints

Camera & Rendering

Scene & Inspection

Volume Grids (Blender 5.0+)

Asset Integrations

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