Blender Astra MCP

Let your AI agent build Blender scenes. All of Blender, four tools, 338 tokens.

Quick start ·
How it saves tokens ·
Benchmark ·
Safety ·
Example

_{Five execute calls (109 operations) written by Claude, rendered with Cycles in Blender 5.1.
Replay the exact calls: they run in under a second.}

4 MCP tools

338 tokens of fixed context

100 operations per call

14–22x less context than other Blender servers

Why it matters

Every MCP client sends each server's tool definitions to the model on every request, before you
type anything. Most Blender servers expose 26 to 31 tools and spend thousands of tokens that way.
That's context your agent can't use for your scene, your code or its own reasoning.

Blender Astra MCP exposes four tools, discover, execute, inspect and capture,
and still reaches the whole Blender API.

Quick start

You need Blender 4.2+ and uv.

1. Install the Blender add-on

uvx blender-astra-mcp install-addon

In Blender, open Edit → Preferences → Add-ons and enable Blender Astra MCP. Then press N in
the 3D Viewport, open the Astra MCP tab and click Start bridge.

2. Connect your agent

claude mcp add blender -- uvx blender-astra-mcp

codex mcp add blender -- uvx blender-astra-mcp

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

If a desktop app can't find uvx, use its absolute path (which uvx or where uvx).

3. Ask for something

Build a small lighthouse island at golden hour: a red-and-white tower, a keeper's house, a few
pines, rocks and a sailboat. Batch your edits, then capture a preview.

How four tools reach all of Blender

Most servers ship one tool per action, and every definition rides along with every request. This
server keeps the menu short and hands the details over only when the agent asks for them:

sequenceDiagram
    autonumber
    participant A as AI agent
    participant M as Blender Astra MCP
    participant B as Blender
    Note over A,M: Each request carries only 4 tool definitions, 338 tokens
    A->>M: discover()
    M-->>A: 16 operation summaries, 189 tokens, once
    A->>M: discover("array")
    M-->>A: argument contract for one operation
    A->>M: execute(43 steps)
    M->>B: validated batch, run on Blender's main thread
    M-->>A: ok, completed 43, 28 tokens
    A->>M: capture()
    M-->>A: preview image at the scene's aspect ratio

The five calls behind the animation above, and what each one added:

Benchmark

_{Tool definitions plus server instructions from each server's real initialize and
tools/list responses, tokenized with tiktoken o200k_base.
Method, raw data, discovery costs and caveats.}

What the agent can do

Safety

Blender stays in control. You choose permissions in the add-on panel when you start the bridge, and
the agent can't change them.

• Write and render are on by default. Delete, save and python are off.
• Python is unrestricted local code execution. Turn it on only for agents you trust.
• The bridge listens on loopback only and needs a fresh random token each time you start it.
• Deletes need confirm: true. Saves and renders never overwrite existing files.
• Interactive sessions get an undo checkpoint before every batch.
• No telemetry.

Details: SECURITY.md.

How it compares

Choose by what you need, not just context size:

• Blender Lab's official server also searches Blender's manual and API docs, which helps agents
  write correct bpy.
• ahujasid's server bundles asset providers (Poly Haven, Sketchfab, Hyper3D and others).
• This server keeps the fixed context small, batches edits, gates risky actions behind
  permissions, and still reaches the whole API through python when you allow it.

More

uvx --from blender-astra-mcp blender-astra discover
uvx --from blender-astra-mcp blender-astra inspect
uvx --from blender-astra-mcp blender-astra execute --params '{"steps":[{"op":"primitive","kind":"cube","name":"Demo"}]}'
uvx --from blender-astra-mcp blender-astra capture --params '{"filename":"preview.png","size":768}'

PowerShell can pipe a file instead of quoting JSON:
Get-Content -Raw examples/lighthouse/01-sky-and-sea.json | uvx --from blender-astra-mcp blender-astra execute --params -

Captures, renders and saves go to the bridge's exports/ folder, and the CLI prints the filename.

Each running bridge writes a connection descriptor. If more than one exists, set
BLENDER_COMPACT_CONNECTION to the one you want:

• 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 a scene at random. Opening a different file stops the
bridge. After a crash, delete only the stale descriptor.

• Add-on: download blender-astra-mcp-addon-<version>.zip from
  Releases and use
  Install from Disk in Blender's add-on preferences, or run
  uvx blender-astra-mcp install-addon --zip addon.zip.
• Server from source: clone the repository, run uv sync --frozen, and point your client at
  uv run --directory /absolute/path/to/blender-astra-mcp blender-astra-mcp.

Configs that use the old blender-compact-mcp command keep working.

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

Blender's timer accepts bounded socket input and runs operations on Blender's main thread. No
background thread touches Blender data. discover returns readable argument contracts, and the add-on
validates every batch again before running it. A batch that fails partway reports which step failed
and what already ran. See design.

uv sync --frozen
uv run ruff check --config pyproject.toml .
uv run ruff format --check --config pyproject.toml .
uv run pytest -q

Tests that need Blender skip unless BLENDER_EXE points at a Blender executable. Set
BLENDER_TEST_UI=1 to also test interactive timers and undo. They launch separate factory-startup
Blender processes and never touch your scenes or preferences. Results:
validation.

scripts/demo_host.py runs a headless bridge on an empty scene for replaying examples/.
scripts/bench_tool_context.py and scripts/context_chart.py reproduce the benchmark and chart.