cavi-ai/blender-mcp

Local-first MCP tools for Blender scene inspection, mesh editing, previews and
game asset export. The server publishes 13 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. Dependencies are pinned in
uv.lock.
bash
git clone https://github.com/cavi-ai/blender-mcp.git
cd blender-mcp
uv sync --locked
Start a dedicated Blender session with the bridge. Use the absolute path to this
checkout:
bash
blender --factory-startup --python /path/to/blender-mcp/scripts/startbridge.py
--factory-startup opens a separate default scene without loading or saving user
preferences. The stdio MCP server never launches or authenticates Blender by
itself; use the runtime CLI when you want it to start a dedicated session.
## Quickstart
Register the installed entry point with your MCP client:
json
"mcpServers": {
"blender": {
"command": "/path/to/blender-mcp/.venv/bin/cavi-blender-mcp"
Call sceneinfo first. Then inspect the session with sessioncontrol:
json
{"action": "inspect"}
Claim the returned projectid and pass the returned leaseid on mutations:
json
"action": "claim",
"owner": "asset-agent",
"expectedproject": " ",
"ttlseconds": 600
Make a bounded change with objectedit:
json
"action": "createprimitive",
"name": "Crate01",
"kind": "cube",
"leaseid": " "
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:
bash
cavi-blender-mcp runtime start
cavi-blender-mcp runtime status
cavi-blender-mcp runtime restart --lease-id
## 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 export; USD export; 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, animation QA and retargeting.
Previews: isolated PNG previews, lit Eevee previews and multi-view review
sheets.
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,