Blender Geometry MCP

Blender Geometry MCP gives external agents a structured production interface to Blender for buildings, vehicles, characters, props, and environment assets. It uses an installable Blender extension and a separate stdio MCP server. Normal modeling does not require arbitrary Python execution.

Capabilities

• Scene and object inspection with transforms, bounds, topology, materials, and UV counts
• Primitive, indexed mesh, and tubular sweep creation
• Batch execution for fast multi-part procedural builds
• Transforms, duplication, parenting, joining, collections, and safe modifiers
• Principled PBR material creation and assignment
• UV projection, smooth/flat shading, mesh checks, and repair
• Decimated LOD generation and box/convex-hull collision proxies
• Generic character armatures, mesh binding, and character rig validation
• Rigid pivot hierarchies for car suspension, wheels, doors, and moving building parts
• Auto-framed preview rendering, .blend checkpoints, and glTF/GLB export

The existing scripts in build/ remain available as reference vehicle tooling; the MCP API is general-purpose and does not depend on their hard-coded paths.

Install The Blender Extension

1. Create the extension archive from the repository root:

   New-Item -ItemType Directory -Force dist | Out-Null
   Compress-Archive -Path blender_addon/geometry_agent/* -DestinationPath dist/geometry_agent-1.0.0.zip -Force
   

   The archive contains blender_manifest.toml and the add-on Python files at its root.

2. In Blender, open Edit > Preferences > Get Extensions.

3. Use Install from Disk and select the archive.

4. Enable Geometry Agent if Blender does not enable it automatically.

5. Open View3D > Sidebar > Geometry Agent.

6. Click Copy Token, then Start Geometry Agent Server.

The add-on listens only on 127.0.0.1, uses port 8765 by default, and requires the generated token on every request. Leave Allow Arbitrary Python disabled.

Run The MCP Server

The MCP server requires Python 3.10+ and uv or another Python package runner.

$env:BLENDER_AGENT_TOKEN = "paste-token-from-blender"
uv run --directory mcp_server geometry-mcp

For OpenCode, merge opencode.example.json into the project or global opencode.json. Set BLENDER_AGENT_TOKEN before starting OpenCode. The example uses the repository-relative mcp_server path. OpenCode configuration changes require a restart.

Agent Workflow

1. Call blender_status, then inspect_scene before changing an existing file.
2. Use batch_operations for coherent repeated creation and assembly steps.
3. Build in named collections and preserve editable modifiers until approval.
4. Use create_pivot_rig for rigid vehicles and moving architecture.
5. Use create_armature and bind_rig for simple deforming characters.
6. Generate UVs and assign standard Principled PBR materials.
7. Render multiple preview views and correct proportions before adding detail.
8. Validate meshes and rigs, generate deliberate LODs and collision, then export GLB.
9. Save a .blend checkpoint before destructive joins or modifier application.

LOD decimation, automatic weights, and convex hulls are starting points, not art direction. Agents should inspect silhouettes, deformation, ground contact, material continuity, and collision coverage before accepting generated results.

Development

uv run --directory mcp_server python -m unittest discover -s tests -v
uv run --directory mcp_server python -m compileall geometry_mcp tests
python -m compileall blender_addon/geometry_agent

The add-on protocol is authenticated JSON-RPC 2.0 over newline-delimited JSON. See blender_addon/geometry_agent/README.md for method contracts and mcp_server/README.md for environment variables.