blender-copilot: an MCP server that lets AI drive Blender on its own

blender-copilot is an MCP server that wires AI straight into Blender. AI clients (Claude, Cursor) use it to call into Blender and handle modeling, rigging, expressions, and exporting on their own. I built it mainly to run the VRChat avatar workflow: modeling, rigging, making visemes, exporting FBX into Unity, and setting up the descriptor. That whole chain is long, fragmented, and pure grunt work, so I just let the AI take over.

How it connects

The connection has three layers. The AI client talks stdio MCP to server.py (FastMCP), the server then connects to Blender over local TCP 9876, and a plugin inside Blender runs a socket server that dispatches commands by their cmd_ prefix, executes them in bpy, and sends the result back.

AI (Claude / Cursor) ──stdio/MCP──► MCP Server ──TCP:9876──► Blender Addon

Why the TCP layer instead of importing bpy directly? Because bpy only lives inside the Blender process and can’t be used as an ordinary library. The only option is to run a service inside via a plugin and have the external server relay through it.

How the tools piled up past three hundred

There are now over three hundred tools, split across more than twenty modules. It happened because every step of building an avatar hit a wall: inspecting the scene, building the base mesh, booleans, cleaning up degenerate faces, UVs, Rigify rigging, converting to VRC Humanoid bone naming, 15 visemes, the ARKit 52 blend shape set, VRCFT Unified Expressions, PhysBones for hair and skirt sway, performance rank validation. Each wall meant patching in another batch. The VRC-related stuff lives in vrc_tools.py, face tracking in face_tracking_tools.py, Unity automation in unity_tools.py. I also wrote a few pipeline-level orchestrations that carry a mesh all the way to FBX in one shot, or push an FBX through Unity into a finished product. For assets I hooked up PolyHaven, Sketchfab, and text/image-to-3D services like Rodin and Tencent Hunyuan, which saves time when you’re missing an HDRI or want to pull a model in quickly.

Pitfalls hit along the way

The nastiest one was TCP timeouts. Long-running jobs like baking normals or retopology outlast the socket, and the other end drops the connection. I later added headless execution, dropping the code into a headless Blender subprocess to run and sidestep the timeout. bpy is very stateful, and one wrong move leaves behind non-manifold geometry, loose vertices, or degenerate faces, so I built a dedicated mesh quality check that runs a health pass before export.

Original, not a fork. The approach is pieced together from a pile of projects across the whole Blender MCP community, with more built on top. MIT, requires Blender 4.0+ and Python 3.10+.