Blender MCP

Local-first MCP tools for Blender scene inspection, mesh editing, previews and game asset export. The server publishes 14 tools over stdio and sends every operation to a bridge that runs on Blender's main thread.

Everything runs on the local machine. The bridge binds only to IPv4 loopback and requires a random session token. There is no arbitrary Python tool, telemetry, external asset download or remote inference.

Install

Requirements: Python 3.11 or newer, uv, and Blender. Native checks target Blender 5.2.3 LTS.

uv tool install cavi-blender-mcp

Start a dedicated Blender session with the bridge:

cavi-blender-mcp runtime start

It runs blender from PATH, CAVI_BLENDER_BIN, or on macOS /Applications/Blender.app, with --factory-startup so the session opens a separate default scene without loading or saving user preferences. The stdio MCP server never launches or authenticates Blender by itself.

To work from a source checkout instead, clone the repository, run uv sync --locked, and start Blender with blender --factory-startup --python scripts/start_bridge.py.

Quickstart

Register the installed entry point with your MCP client:

{
  "mcpServers": {
    "blender": {
      "command": "cavi-blender-mcp"
    }
  }
}

If your client does not inherit your shell's PATH, use the absolute path that which cavi-blender-mcp prints.

Call scene_info first. Then inspect the session with session_control:

{"action": "inspect"}

Claim the returned project_id and pass the returned lease_id on mutations:

{
  "action": "claim",
  "owner": "asset-agent",
  "expected_project": "<project_id>",
  "ttl_seconds": 600
}

Make a bounded change with object_edit:

{
  "action": "create_primitive",
  "name": "Crate_01",
  "kind": "cube",
  "lease_id": "<lease_id>"
}

Read-only calls do not need a lease. Release or expiry never saves, closes or discards a project. See the ownership guide.

You can also let the CLI manage the session:

cavi-blender-mcp runtime start
cavi-blender-mcp runtime status
cavi-blender-mcp runtime restart --lease-id <current-lease>

What it does

• Inspection: scene and object metadata, mesh budgets, texel density, UV stretch, material bindings, bone hierarchies and skin weights.
• Object editing: primitives, custom meshes, transforms, origins, names, sockets, duplicates, parents, collections and shape keys.
• Mesh preparation: modifiers, UV unwrapping, decimation, LOD chains, QuadriFlow, lightmap packing, texel density, collision hulls, cleanup, booleans, joins, splits, mirrors, arrays and shells.
• Materials: PBR slot assignment with packed workspace textures, UV transforms, alpha modes and material QA.
• Baking: normal, ambient-occlusion, curvature and lightmap maps into a new workspace PNG.
• Assets: bounded GLB, FBX, OBJ and USD import; GLB morph targets and shape-key animation; static, skinned and animated FBX, GLB and USD export; FBX and USD texture sidecars; Unity, Unreal and Godot axis presets; LOD groups, collision naming and bake pairs.
• Rigging: armature creation, automatic skin binding, weight repair, pose authoring, action creation, clip/NLA management, animation QA and retargeting.
• Previews: isolated PNG previews, lit Eevee previews and multi-view review sheets.
• Levels: heightmap or procedural terrain, bulk placement and surface snapping.
• Scatter: fixed Geometry Nodes instancing with explicit budgets.
• Ownership: edit leases shared by independent MCP clients.

Every input and output is bounded. When Blender does not expose an operation, the server reports the boundary and fails closed instead of simulating a write.

Documentation

The versioned documentation is published to cavi-ai.xyz/docs/blender-mcp. The source lives in this repository.

• Overview, Installation, Quickstart
• Inspect a scene
• Prepare meshes
• Materials and UVs
• Import and export assets
• Generate a mesh locally
• Rig and animate
• Preview and review
• Tools, CLI, Configuration, Limits
• Security model
• Troubleshooting

Configuration

Set a variable in both Blender's environment and the MCP server's environment when both processes read it. See configuration.

Security

The bridge listens on loopback and requires a random bearer token from a private connection file. Mutations require a claimed edit lease bound to the current project. Paths are confined to the workspace, including through symbolic links, and existing outputs are never overwritten. Changes are never retried after a timeout; inspect the scene before resubmitting an uncertain mutation.

See the security model and SECURITY.md.

Tests

uv sync --locked --dev
uv run --locked python -m unittest discover -s tests
uv run --locked ruff check .
npm ci
npm run eval:protocol

The unit suite does not need Blender. Native checks under tests/blender_*.py run against a disposable factory scene and an empty workspace, including animation QA and retargeting:

blender --background --factory-startup --python-exit-code 1 \
  --python tests/blender_smoke.py -- /path/to/empty/workspace

Docs are built and verified with:

uv run --locked python -m scripts.docs.build
uv run --locked python -m scripts.docs.verify

npm run eval:protocol checks discovery size, catalog token budgets, pagination, surface listing and protocol negotiation. npm run eval:core adds native application checks and requires Blender. See MCP evaluation.

Project status

See GitHub Releases and the changelog. The tool surface can still change before 1.0.

Contributing

See CONTRIBUTING.md.

License

MIT. Third-party product names belong to their owners. No vendor assets, logos or presets are included, and no endorsement is implied.