Frugal Blender MCP

Frugal Blender 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.

Frugal Blender 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 frugal-blender-mcp install-addon

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

2. Connect your agent

claude mcp add blender -- uvx frugal-blender-mcp

codex mcp add blender -- uvx frugal-blender-mcp

{
  "mcpServers": {
    "blender": { "command": "uvx", "args": ["frugal-blender-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 Frugal Blender 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 frugal-blender-mcp frugal-blender discover
uvx --from frugal-blender-mcp frugal-blender inspect
uvx --from frugal-blender-mcp frugal-blender execute --params '{"steps":[{"op":"primitive","kind":"cube","name":"Demo"}]}'
uvx --from frugal-blender-mcp frugal-blender capture --params '{"filename":"preview.png","size":768}'

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

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