Blender Copilot

Python · MIT · ★6

docs · issues

The most comprehensive Blender MCP server — AI-powered 3D creation with 308 tools across 25 modules. Full zero-to-published VRChat avatar pipeline.

最全面的 Blender MCP 伺服器 — AI 驅動的 3D 創作，308 種工具橫跨 25 模組。完整的從零到上傳 VRChat Avatar 流水線。

Features / 功能特色

Core Tools (82 tools in server.py)

Asset Integration (20 tools in server.py)

VRC Avatar Pipeline (23 tools in vrc_tools.py)

Advanced Mesh Tools (10 tools in blender_master_tools.py)

Sculpt & Texture Bake (14 tools in sculpt_bake_tools.py)

Face Tracking — ARKit 52 + Unified (10 tools in face_tracking_tools.py)

Rigify Integration (6 tools in rigify_tools.py)

Unity Automation (15 tools in unity_tools.py)

Script Execution (4 tools in script_tools.py)

Render Presets (8 tools in render_tools.py)

Scene Profiles (9 tools in scene_tools.py)

Modifier Registry (9 tools in modifier_tools.py)

Animation (9 tools in animation_tools.py)

Materials (7 tools in material_tools.py)

UV Mapping (8 tools in uv_tools.py)

Curves (7 tools in curve_tools.py)

Physics (7 tools in physics_tools.py)

Armature & Bones (7 tools in armature_tools.py)

File I/O (6 tools in io_tools.py)

Lighting (5 tools in lighting_tools.py)

Measurement & Verification (6 tools in measurement_tools.py)

Pipeline Orchestration (5 tools in pipeline_tools.py)

Blender Addon (112 commands, 2915 lines)

The addon (addon/__init__.py) runs inside Blender and handles all commands via TCP.
Includes full UI panels for:

• PolyHaven Browser — search and import HDRIs, textures, models
• Sketchfab Browser — search, preview, download models
• Hyper3D (Rodin) — text/image to 3D generation with progress tracking
• Hunyuan3D — Tencent's 3D generation pipeline
• Copilot Panel — connection management, port config

Architecture / 架構

┌─────────────────┐    stdio/MCP     ┌──────────────────┐    TCP:9876    ┌──────────────┐
│  AI (Claude,    │ ◄──────────────► │  MCP Server      │ ◄────────────► │  Blender     │
│  Cursor, etc.)  │                  │  (server.py)     │                │  Addon       │
└─────────────────┘                  └──────────────────┘                └──────────────┘
                                     │
                                     ├── vrc_tools.py (23 VRC tools)
                                     ├── blender_master_tools.py (10 advanced tools)
                                     ├── sculpt_bake_tools.py (14 sculpt/bake tools)
                                     ├── face_tracking_tools.py (10 ARKit/Unified tools)
                                     ├── rigify_tools.py (6 Rigify tools)
                                     ├── unity_tools.py (15 Unity automation tools)
                                     └── pipeline_tools.py (5 orchestration tools)

• MCP Server (server.py): FastMCP server exposing 185 tools via stdio transport
• VRC Tools (vrc_tools.py): VRChat avatar pipeline — validation, rigging, visemes, PhysBones, export
• Master Tools (blender_master_tools.py): Advanced mesh — BMesh, retopology, procedural generation
• Sculpt & Bake (sculpt_bake_tools.py): Sculpt mode, brush strokes, texture baking (normal/AO/diffuse)
• Face Tracking (face_tracking_tools.py): ARKit 52 blend shapes, VRCFT Unified Expressions, tongue/eye tracking
• Rigify (rigify_tools.py): Meta-rig generation, fitting, VRC bone conversion, IK configuration
• Unity (unity_tools.py): C# EditorScript generation, Unity CLI automation, avatar descriptor, animator, shaders
• Pipeline (pipeline_tools.py): End-to-end orchestration — mesh-to-FBX, FBX-to-Unity, face tracking setup
• Blender Addon (addon/__init__.py): TCP socket server + CommandExecutor with cmd_ dispatch pattern

Installation / 安裝

1. Install the MCP Server / 安裝 MCP 伺服器

# Using uv (recommended / 推薦)
uv pip install -e .

# Or using pip
pip install -e .

2. Install the Blender Addon / 安裝 Blender 外掛

Option A: Copy directly / 直接複製

Copy addon/__init__.py to your Blender addons directory:

# Windows
%APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\blender_copilot.py

# macOS
~/Library/Application Support/Blender/<version>/scripts/addons/blender_copilot.py

# Linux
~/.config/blender/<version>/scripts/addons/blender_copilot.py

Option B: Blender Extension (4.2+) / Blender 擴展

Copy the entire addon/ folder to your extensions directory:

# Windows
%APPDATA%\Blender Foundation\Blender\<version>\extensions\user\blender_copilot\

3. Enable the Addon / 啟用外掛

1. Open Blender → Edit → Preferences → Add-ons
2. Search for "Blender Copilot"
3. Enable it
4. In the 3D Viewport sidebar (N key) → Copilot tab → Click "Connect to AI"

4. Configure Your AI Client / 配置 AI 客戶端

Add to your .mcp.json or MCP config:

{
  "mcpServers": {
    "blender-copilot": {
      "command": "uv",
      "args": ["--directory", "/path/to/blender-copilot", "run", "blender-copilot"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "blender-copilot": {
      "command": "blender-copilot"
    }
  }
}

Auto-Start (Optional) / 自動啟動（可選）

Create a startup script to automatically start the Copilot server when Blender launches:

Save as mcp_autostart.py in Blender's startup folder:

# Windows: %APPDATA%\Blender Foundation\Blender\<version>\scripts\startup\
# macOS: ~/Library/Application Support/Blender/<version>/scripts/startup/
# Linux: ~/.config/blender/<version>/scripts/startup/

import bpy

def _auto_start():
    try:
        bpy.context.scene.copilot_port = 9876
        bpy.ops.copilot.start()
        print("[Copilot] Auto-started")
    except:
        pass
    return None

def register():
    bpy.app.timers.register(_auto_start, first_interval=3.0)

def unregister():
    pass

Environment Variables / 環境變數

Compatibility / 相容性

• Blender: 4.0+ (tested on 4.2, 5.0, 5.1)
• Python: 3.10+
• OS: Windows, macOS, Linux
• AI Clients: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, or any MCP-compatible client

Documentation / 文檔

• docs/MODELER_KNOWLEDGE_BASE.md — VRChat avatar pipeline reference (performance ranks, export settings, weight painting rules)
• docs/MAYO_VRC_MANUAL.md — Complete operation manual for the Mayo avatar project

License / 授權

MIT License - see LICENSE

Credits / 致謝

Original work by DWGX. Not a fork.

Inspired by the Blender MCP ecosystem, with features consolidated and expanded from research across 17+ community projects.

本項目為原創作品，非 fork。靈感來自 Blender MCP 生態系統，整合並擴展了 17+ 個社群項目的功能。