Blender Copilot Server

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 流水線。

License: MIT Python 3.10+ Blender 4.0+

---

Features / 功能特色

Core Tools (82 tools in server.py)

Category	Tools	Description
Scene Inspection	4	Get scene info, object details, analysis, viewport screenshots
Object Creation	4	Primitives, curves, 3D text, armatures
Transforms	6	Translate, rotate, scale, apply, snap to ground, set origin
Object Management	9	Duplicate, delete, select, parent, visibility, hierarchy, rename
Mesh Editing	14	Boolean, join, separate, subdivide, extrude, bevel, inset, decimate, remesh, normals, fill holes
Modifiers	5	Add/apply/remove modifiers, linear array, circular array
Materials	9	PBR materials, glass, metal, emission, texture, Principled BSDF, list, batch assign
World/Environment	4	Background color, HDRI, procedural sky, volumetric fog
Camera & Lighting	3	Camera setup, studio lighting presets, custom lights
Render & Export	3	Render to image, configure settings, export (glTF/OBJ/FBX/STL/USD/PLY)
Collections	4	Create, move objects, list, visibility
Constraints	2	Add/remove constraints (Track To, Copy Location, etc.)
Batch Operations	5	Batch transform, delete, align, distribute, center
Animation	4	Keyframes, animation range, set frame, clear animation
Physics	4	Rigid body, cloth, particles, bake physics
UV Mapping	2	Smart UV project, UV unwrap
Code Execution	1	Sandboxed Python execution inside Blender
Optimization	1	Clean orphan data, merge duplicate vertices

Asset Integration (20 tools in server.py)

Source	Tools	Description
PolyHaven	4	Search/download free HDRIs, textures, and 3D models from polyhaven.com
Sketchfab	4	Search/preview/download models from Sketchfab (API key required)
Hyper3D (Rodin)	4	AI text/image-to-3D generation via Rodin API
Hunyuan3D	4	Tencent's text/image-to-3D generation
Wrappers	4	Convenience tools for text-to-3D and image-to-3D workflows

VRC Avatar Pipeline (23 tools in vrc_tools.py)

Category	Tools	Description
Validation	2	Performance rank check (PC/Quest), export readiness
Rigging	5	Humanoid armature, bone renaming, auto-weight, weight check
Visemes & Eyes	2	15 VRC visemes from base shapes, eye tracking setup
PhysBones	3	Chain setup, physics config (hair/tail/ears/skirt), dynamics budget
Accessories	2	Auto-align imported accessories, attach to bones
Optimization	3	Smart decimate (preserves shape keys), material merge, texture atlas bake
Avatar Features	4	Expression menu, contacts (headpat/boop), gestures, animator generation
Import/Export	2	VRC-correct FBX import and export

Advanced Mesh Tools (10 tools in blender_master_tools.py)

Tool	Description
bmesh_operation	Low-level BMesh operations (dissolve, collapse, merge, knife)
topology_edge_loops	Edge loop analysis and insertion
procedural_generate	Parametric mesh generation
precision_weight_paint	Vertex-level weight painting with smoothstep interpolation
build_material_nodes	Programmatic Shader Editor node trees
smart_uv_tools	Advanced UV tools (LSCM, angle-based, pack islands)
rig_tools	IK/FK chains, stretch-to, custom shapes
retopology	Quad-based retopology from high-poly
boolean_cleanup	Post-boolean topology repair
create_facial_topology	Face topology from landmarks

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

Category	Tools	Description
Sculpt Mode	6	Enter sculpt, brush strokes, masking, remesh, detail flood, face set extract
Shape Keys	2	Sculpt to shape key, cloth sim to shape key
Texture Bake	4	Normal map, AO, diffuse atlas, general bake (Cycles)
Paint & Sim	2	Texture paint fill, cloth simulation for modeling

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

Tool	Description
ft_setup_face_vertex_groups	Auto-detect facial landmarks → 28 vertex groups
ft_create_arkit_shapes	Create all 52 ARKit blend shapes (procedural/template/from_existing)
ft_create_unified_expressions	Generate 70+ VRCFT Unified Expressions
ft_sculpt_shape_key	AI-guided shape key sculpting via vertex displacement
ft_validate_shapes	Validate against ARKit/Unified standard
ft_mirror_shape_key	Mirror Left↔Right shape keys
ft_combine_shape_keys	Combine multiple shapes with weights
ft_setup_tongue_tracking	Tongue bone chain + blend shapes
ft_setup_eye_tracking_full	Extended eye tracking (12 shapes)
ft_export_shape_key_report	Shape key report (JSON/markdown)

Rigify Integration (6 tools in rigify_tools.py)

Tool	Description
rigify_create_metarig	Generate Rigify meta-rig (human/quadruped/bird/etc.)
rigify_fit_metarig	Auto-fit meta-rig to mesh proportions (proportional/snap)
rigify_generate_rig	Generate production rig from meta-rig
rigify_to_vrc	Convert DEF-bones to VRC/Unity Humanoid naming
rigify_add_face_rig	Add face rig bones (full/basic/eyes_only)
rigify_configure_ik	Configure IK for VRC full-body tracking (3/6/10-point)

Unity Automation (15 tools in unity_tools.py)

Category	Tools	Description
Project Setup	1	Verify Unity project, VRC SDK presence
Import	1	Import FBX with humanoid rig, extract materials/textures
Avatar Config	2	Avatar Descriptor setup, pipeline manager
Expressions	2	Expression Menu and Parameters .asset generation
Animation	3	Animator controller, animation clips, gesture layer
Shaders	2	Configure Poiyomi/lilToon/UTS2, material preset generation
Dynamics	2	PhysBone components, ContactSender/Receiver
Build & Publish	2	Build validation, publish to VRChat (CLI + GUI fallback)

Script Execution (4 tools in script_tools.py)

Tool	Description
execute_script_headless	Run Python in headless Blender subprocess (bypasses TCP timeout)
execute_script_on_file	Execute code on an existing .blend file
build_scene_from_json	JSON scene description → bpy script → headless execute
generate_scene_script	Generate bpy script from JSON without executing

Render Presets (8 tools in render_tools.py)

Tool	Description
render_list_presets	List 7 presets (cycles/eevee preview/default/high, workbench)
render_apply_preset	One-click render preset application
render_set_output	Configure output path, format, quality
render_still	Render single frame
render_animation	Render animation (image sequence or FFMPEG video)
render_set_camera	Set/create active render camera
render_get_settings	Get current render config
render_set_world	Set world background (solid color or HDRI)

Scene Profiles (9 tools in scene_tools.py)

Tool	Description
scene_list_profiles	List 10 profiles (preview to 4K, Instagram, YouTube, VRC)
scene_apply_profile	Apply resolution/engine/samples profile
scene_setup_turntable	360° camera turntable animation
scene_create_collection	Create collections with color tags
scene_move_to_collection	Move objects between collections
scene_cleanup	Remove unused materials/meshes/images
scene_stats	Comprehensive scene statistics
scene_set_units	Configure unit system (metric/imperial)
scene_set_visibility	Control object viewport/render visibility

Modifier Registry (9 tools in modifier_tools.py)

Tool	Description
modifier_list_types	List 15 modifier types with validated parameters
modifier_add	Add modifier with type-safe parameter validation
modifier_apply	Apply (finalize) a modifier
modifier_remove	Remove modifier without applying
modifier_list	List all modifiers on an object
modifier_reorder	Move modifier in stack
modifier_apply_all	Apply all modifiers at once
modifier_batch_add	Add same modifier to multiple objects
modifier_preset_smooth_shade	One-click SubD + Smooth + WeightedNormal

Animation (9 tools in animation_tools.py)

Tool	Description
anim_insert_keyframe	Insert keyframe on any property
anim_insert_keyframes_batch	Insert multiple keyframes at once
anim_delete_keyframe	Delete keyframe
anim_clear_all	Clear all animation from object
anim_set_interpolation	Set interpolation type (Bezier, Linear, etc.)
anim_set_frame_range	Set frame range and FPS
anim_bounce	Bouncing animation preset
anim_orbit	Orbital/circular motion preset
anim_get_info	Get animation data summary

Materials (7 tools in material_tools.py)

Tool	Description
material_list_presets	List 12 presets (metals, glass, skin, fabric, etc.)
material_create_preset	Create material from preset
material_create_pbr	Full PBR material with all parameters
material_assign	Assign material to object
material_list	List materials on object or in scene
material_duplicate	Duplicate existing material
material_set_texture	Add image texture (albedo, normal, roughness, etc.)

UV Mapping (8 tools in uv_tools.py)

Tool	Description
uv_smart_unwrap	Smart UV Project (auto, angle-based)
uv_unwrap	Standard unwrap (follows seams)
uv_project_from_view	Cube/cylinder/sphere projection
uv_mark_seams	Mark UV seams (manual or auto by angle)
uv_pack_islands	Pack UV islands efficiently
uv_get_info	Get UV layer info
uv_add_layer	Add new UV layer
uv_remove_layer	Remove UV layer

Curves (7 tools in curve_tools.py)

Tool	Description
curve_create_bezier	Create Bezier curve with custom points
curve_create_nurbs	Create NURBS curve
curve_create_path	Create NURBS path (for follow-path)
curve_create_circle	Create circle curve (bevel profile)
curve_create_text	Create 3D text object
curve_to_mesh	Convert curve to mesh
curve_set_bevel	Set curve bevel (tube/pipe effect)

Physics (7 tools in physics_tools.py)

Tool	Description
physics_add_rigid_body	Rigid body physics (active/passive)
physics_add_cloth	Cloth simulation
physics_add_collision	Collision surface for cloth/particles
physics_add_particle_system	Particle emitter
physics_add_soft_body	Soft body physics
physics_bake	Bake all physics simulations
physics_remove	Remove physics from object

Armature & Bones (7 tools in armature_tools.py)

Tool	Description
armature_create	Create new armature
armature_add_bone	Add individual bone
armature_add_bones_chain	Add connected bone chain (spine, arm, finger)
armature_add_constraint	Add pose bone constraint (IK, Copy Rot, etc.)
armature_auto_weight	Parent mesh to armature with automatic weights
armature_list_bones	List all bones with hierarchy
armature_set_pose	Set bone rotations/positions

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

Tool	Description
io_import_file	Import any 3D file (auto-detect: FBX, OBJ, glTF, STL, USD, PLY, ABC)
io_export_fbx	Export FBX (VRChat-optimized defaults)
io_export_gltf	Export glTF/GLB (web-ready)
io_export_obj	Export OBJ (universal mesh)
io_export_stl	Export STL (3D printing)
io_export_usd	Export USD (Pixar format)

Lighting (5 tools in lighting_tools.py)

Tool	Description
light_add	Add any light type (point, sun, spot, area)
light_setup_three_point	Classic 3-point lighting rig
light_setup_studio	Professional studio softbox setup
light_list	List all lights with properties
light_modify	Modify existing light properties

Measurement & Verification (6 tools in measurement_tools.py)

Tool	Description
measure_distance	Distance between objects
measure_dimensions	Object bounding box and mesh stats
measure_overlap	Bounding box overlap detection
measure_symmetry	Mesh symmetry analysis
mesh_quality_check	Non-manifold, loose verts, degenerate faces, dupes
measure_alignment	Check multi-object axis alignment

Pipeline Orchestration (5 tools in pipeline_tools.py)

Tool	Description
pipeline_avatar_from_mesh	Full Blender-side: mesh → armature → shape keys → FBX
pipeline_blender_to_unity	Full Unity-side: FBX → import → descriptor → build
pipeline_face_tracking_setup	Complete: vertex groups → ARKit 52 → Unified → validate
pipeline_validate_full	Comprehensive go/no-go report for VRC upload
pipeline_generate_blueprint	Export all config JSONs alongside FBX

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 / 環境變數

Variable	Default	Description
BLENDER_HOST	localhost	Blender addon TCP host
BLENDER_PORT	9876	Blender addon TCP port

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+ 個社群項目的功能。