Optional Blender MCP

Status: optional interactive tooling, not a build dependency. Blender MCP is useful for exploring a local part scene, moving the viewport and iterating on a head/hand mesh without a manual UI walkthrough. The authoritative asset pipeline remains the headless CLI plus audit/fit/inspect; CI, tests and release builds must continue to work with no Blender process and no MCP server.

This project does not vend the third-party addon or pin a runtime MCP dependency. Install it outside the repository and keep generated scenes under tmp/.

What it adds

With Blender MCP connected, an agent can:

query the current scene and object data;
run small bpy snippets through the MCP bridge;
capture a viewport screenshot for visual checks;
inspect or modify a local part scene before exporting a GLB.

It does not replace:

python3 tools/blender_assets.py audit/fit/inspect;
python3 tools/npc_proportions.py;
the Godot capture and smoke gates;
the project's licence/provenance review.

Prerequisites

Blender 5.2 LTS, installed as the org.blender.Blender flatpak (the project standard).
An MCP-capable client.
The upstream BlenderMCP addon (addon.py) and its MCP server.
uv/uvx if you use the server's uvx blender-mcp launcher; a local install of the server package is equally valid.

Check the upstream README for the current package/addon version and any command changes before installing. Do not copy the addon into this repository.

Setup

1. Install the Blender addon

Download or clone the upstream BlenderMCP project.
In Blender: Edit → Preferences → Add-ons → Install from Disk, select addon.py from that checkout.
Enable Interface: Blender MCP.
Open the 3D View sidebar (N panel), find the BlenderMCP tab, and click Connect to MCP server. The default server listens on localhost:9876.

The addon must be running inside the Blender process that has the scene open. Starting a second Blender instance does not connect the first one.

2. Configure the MCP client

For Pi, add the server at user scope so it is not committed into the project:

pi mcp add blender -- uvx blender-mcp
pi mcp list

Then start/reload Pi and use /mcp to inspect the connection. Other clients use their normal MCP server configuration. A generic JSON example:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

For a client with a different config schema, use the equivalent server command and keep the server name blender. Restart/reload the client after adding it, then request the tool list and run a harmless get_scene_info before editing.

3. Connect through the flatpak

Start Blender through the project's normal flatpak command, open the local part scene, and connect from the sidebar. If the client cannot reach the addon:

confirm the addon panel says connected;
confirm the client is launching the MCP server, not just a shell;
check port 9876 is not occupied;
if the flatpak sandbox is blocking localhost networking, grant network permission only for this interactive use, for example: flatpak override --user --share=network org.blender.Blender (review the permission change afterwards; do not add it to CI or build scripts).
restart both the MCP client and Blender after changing the addon or config.

Recommended part-workflow

Create a local scene, for example tmp/npc-parts/npc_casual/head.blend, or open a copy of an exported part GLB. Never save over the tracked assets/models/npc/npc_base.blend.
Ask the MCP client for get_scene_info, then inspect the object/bone/mesh names it reports.
Use execute_blender_code for small, reversible edits. Prefer adding a new object or modifier over deleting existing geometry; keep a backup copy.
Use get_viewport_screenshot after camera/material changes to check the head/face/hand before exporting.
Export a local GLB under tmp/npc-parts/, not directly into assets/models/.

Run the normal gates on the exported file:

flatpak run org.blender.Blender --background \
  --python "$PWD/tools/blender_assets.py" -- \
  inspect --file "$PWD/tmp/npc-parts/head.glb" --category npc --json
python3 tools/blender_assets.py audit
python3 tools/blender_assets.py fit
python3 tools/npc_proportions.py report

Only after the part is reviewed and the contract passes should it be assembled into a character and rebuilt through the headless pipeline.

Safety and project rules

MCP is not part of project.godot, the build, CI, tests, release packages or runtime.
Do not commit .blend part scenes, MCP configuration, API keys or generated previews. The working set stays in tmp/.
Do not use MCP to bypass the contract, budgets, AO/UV rules or licence gate.
The 13 core bones must remain at their rest positions; extra optional bones are allowed only if NpcAvatar and the audit/tests still pass.
Prefer scripted headless changes for reproducible work; MCP is for the interactive exploration and review that is awkward in a one-shot script.
If MCP is unavailable, use the headless CLI and document the manual step; never make the project depend on MCP being present.

Troubleshooting

Symptom	Check
Client cannot find `blender`	MCP client config path/schema; restart client; confirm server command exists
`Connection refused`	Addon Connect to MCP server pressed; Blender still running; port 9876
Tools return stale scene data	Refresh scene/object query after edits; restart the connection if needed
Flatpak cannot reach localhost	Check flatpak network permission; grant only for interactive use
Changes look wrong in export	Re-import the GLB with `inspect`; check transforms, scale, UVs and materials
Contract audit fails	Fix the mesh/bones first; do not edit the audit expectations around a broken asset

6.0 KiB Raw Blame History