Blender Compact MCP for Astra

Four tools for Blender: inspect, discover, execute, capture. Batch related edits, fetch operation arguments only when needed, and return bounded summaries.

Version 0.2 adds existing-scene editing and an unrestricted Python operation for the full Blender API, while keeping four MCP tools and on-demand operation discovery.

What works

• Existing object transforms and material editing, primitives, linked arrays, cameras and lights.

• Batched modifiers, RNA properties, keyframes, frame evaluation and RNA discovery.

• Full Python access for Geometry Nodes, rigging, simulations, import/export and other bpy workflows. Discover python, then execute {"op":"python","code":"..."}. Assign result for a bounded JSON response; bpy, params and output_dir are available in the script.

• Camera or interactive viewport previews; render uses current scene resolution and supports animation.

• Independent write/render/delete/save toggles and an additional Python toggle, fixed at bridge start. Python is unrestricted local code execution and can bypass all the narrower toggles. It defaults off.

• Interactive undo checkpoints and explicit partial batch errors. Long operations block Blender; the MCP execute timeout is configurable and does not cancel work.

The new capabilities are not fully validated. External asset-provider integrations are not bundled. The historical benchmark below measures batching only; no cross-product token comparison is available yet.

Quick start

Requirements: Blender, Python 3.11+ and uv.

1. Download compact_blender-0.2.0.zip from this repository's Releases.

2. In Blender, open Edit → Preferences → Add-ons → Install from Disk, choose the ZIP and enable Compact Blender MCP.

3. In the 3D Viewport sidebar (N), open Compact MCP. Review permissions and click Start bridge. Write and render default on; delete, save and Python default off. Enable Python for full API access. Stop/restart to change permissions.

4. Clone this repository and run uv sync --frozen inside it.

5. Add the MCP command below to your client. Use an absolute path to your checkout:

{
  "mcpServers": {
    "blender-compact": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/blender-compact-mcp", "blender-compact-mcp"]
    }
  }
}

If uv is not on the GUI application's PATH, set command to its absolute executable path. Use the client's own MCP configuration format; the block above illustrates a common JSON form. No token needs to be pasted into model context. The bridge reads the local descriptor.

For multiple Blender instances, set BLENDER_COMPACT_CONNECTION to the intended descriptor: Windows %LOCALAPPDATA%/blender-compact-mcp/connection-<pid>.json; Linux/macOS ${XDG_STATE_HOME:-~/.local/state}/blender-compact-mcp/connection-<pid>.json. Ambiguous discovery fails rather than picking an arbitrary scene. After a crash, remove only the stale instance's descriptor. Normal shutdown removes it; opening a different file stops the server.

Try it

First ask the agent to discover primitive, array, material, and assign_material, then:

Create a teal cube named Demo at [0,0,1], then make 49 linked copies along X. Inspect the first and last object only. Do not render until I ask.

Or use the CLI:

uv run blender-compact discover
uv run blender-compact inspect
uv run blender-compact execute --params '{"steps":[{"op":"primitive","kind":"cube","name":"Demo","location":[0,0,1]},{"op":"array","name":"Demo","count":49,"offset":[2.5,0,0],"prefix":"Copy"}]}'

For PowerShell, avoid nested JSON quoting by piping a file:

Get-Content -Raw examples/scene.json | uv run blender-compact execute --params -

That example creates 50 cubes, a floor, camera and lights in one batch. Names must be unique; it intentionally refuses to overwrite existing objects. Run it in a fresh scene.

uv run blender-compact capture --params '{"filename":"preview.png","size":768}'

The CLI returns an output filename; MCP returns an image. Exports go under the local state directory's exports/ folder. A repeated filename is refused. Capture does not include other apps or take a desktop screenshot. Save exports a copy, never overwrites a file, and requires save permission.

Measured overhead, not marketing

In a real Blender test, the same 50 transforms produced identical final object properties:

47.77% fewer payload tokens, using cl100k_base. Results are measured from actual requests and responses, not guessed from characters. This isolates batching using our own bridge in both cases. It excludes model reasoning, conversation history, caching, tool-call envelopes, images, setup and discovery. It is not a benchmark against another product and not a claim of 47.77% lower total bills. The agent's quality, task and client-side tool loading still matter. See validation.

Architecture

AI client -- MCP stdio --> Python SDK bridge -- authenticated loopback JSON --> Blender add-on
CLI ----------------------------------------------^                        bpy.app.timers

Blender's timer accepts bounded socket input and executes operations on its main thread. No Python background thread accesses Blender data. The optional Python operation has full local process privileges. discover returns human-readable argument contracts; operations are validated again by the add-on before execution. See design and security.

Development and tests

uv sync --frozen
uv run ruff check --config pyproject.toml .
uv run ruff format --check --config pyproject.toml .
uv run pytest -q
uv run python scripts/package_addon.py
uv build

Without BLENDER_EXE, real Blender tests explicitly skip. Enable them on Windows:

$env:BLENDER_EXE = 'D:/blender/blender.exe' # use your installed path
$env:BLENDER_TEST_UI = '1' # also check actual UI timer execution and Undo
uv run pytest -q

The tests launch separate factory-startup processes. They never connect to an already-open user scene or save user preferences. Outputs and logs go to ignored artifacts/. The UI helper is hidden on Windows and exits automatically. Linux UI tests require a display; background tests do not.

The package ZIP contains only the add-on's Python sources. The wheel contains the MCP bridge/CLI; installing the wheel alone does not install the Blender add-on.

MIT licensed. Independent software, not affiliated with Blender or any model provider.