Frugal Blender MCP

io.github.mohakmalviyaPublished by GitHub account mohakmalviyav0.2.0Updated Oct 24, 2026

Let AI agents build Blender scenes with four compact tools: discover, execute, inspect, capture.

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & Design

Overview

AI-generated overview

Token-frugal Blender MCP server with four tools (discover, execute, inspect, capture) that lets an agent build, animate and render 3D scenes.

What you can do
  • Discover operation contracts and inspect scene data by name with paging
  • Build and edit scenes: primitives, arrays, transforms, materials, lights, cameras, deletes
  • Refine with any modifier or RNA property, and animate with keyframes and frames
  • Capture previews, render stills or animations, and save .blend copies
  • Run arbitrary bpy Python through the same execute call when enabled
When to use it
Use it when you want an AI agent to author or modify Blender scenes on your desktop while keeping the fixed tool-definition context small, and you are willing to run Blender with the companion add-on bridge.
Requirements
Local process started via uvx (Python/uv) on a desktop machine; Blender 4.2+ with the Frugal Blender MCP add-on installed and its bridge started; the bridge listens on loopback with a fresh random token per session; BLENDER_COMPACT_CONNECTION is needed only to pick among multiple running bridges.
Before you install
Write and render are enabled by default; delete, save and python are off and must be enabled in the add-on panel, which the agent cannot change. Python is unrestricted local code execution, so enable it only for trusted agents. Deletes require confirm: true. Captures, renders and saves are written to the bridge's exports folder. No telemetry is reported.

Installation

In SourceWeft

  1. Open Frugal Blender MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Frugal Blender MCP

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

[Checks] [PyPI] [Blender 4.2+] [MCP] [MIT]

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

[A stylized lighthouse island at sunset with a rotating beam, a bobbing sailboat and moving ocean waves]

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

bash
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 Code
bash
claude mcp add blender -- uvx frugal-blender-mcp
Codex CLI
bash
codex mcp add blender -- uvx frugal-blender-mcp
Claude Desktop,
Cursor, Windsurf
json
{  "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:

mermaid
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
TechniqueWhat it doesEffect
Lazy schemasOperation arguments live behind discover. The agent fetches each one once, only if it uses it.Fixed cost stays at 338 tokens. Even fetching every schema totals 1,256.
BatchingOne execute carries up to 100 operations. array makes up to 200 copies in one step, keyframes sets up to 1,000 keys.The lighthouse took 5 calls, not 109.
Compact resultsexecute returns counts and errors, never the scene echoed back.109 operations returned 202 tokens in total.
Look, don't dumpcapture returns an image. inspect is paged and filtered by name.The agent checks its work without reading huge scene dumps.
Lean definitionsGenerated schema titles, null unions and docstring whitespace are stripped before tools are listed.Definitions shrank from 406 to 289 tokens. A test fails if they grow past 300.
One escape hatchpython runs any bpy code through the same execute call, so it needs no extra tool.Geometry Nodes, rigging, simulation and import/export at zero fixed cost.

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

[The lighthouse scene after each of the five execute calls]

Benchmark

[Fixed context per request: Frugal Blender MCP 338 tokens, Blender Lab official 4,722 tokens, ahujasid 7,464 tokens]
ServerToolsFixed context per request
Frugal Blender MCP4338 tokens
Blender Lab official264,722 tokens (14.0x)
ahujasid mcp-for-blender317,464 tokens (22.1x)

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

NeedOperations
🧱Buildprimitive, array, transform, material, assign_material, light, camera, delete
🎨Refinemodifier (any Blender modifier), properties (any RNA property on objects, data, scene or render), rna (look up property names and enums)
🎬Animatekeyframes, frame
📸Outputcapture (preview back to the agent; EEVEE, or Cycles on request), render (stills or animations), save (a .blend copy)
🐍Anything elsepython: the full bpy API. Off by default.

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

CLI: drive Blender from scripts with the same code path
bash
uvx --from frugal-blender-mcp frugal-blender discoveruvx --from frugal-blender-mcp frugal-blender inspectuvx --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}'

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

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

Multiple Blender instances

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.

Install without uvx
  • Add-on: download frugal-blender-mcp-addon-<version>.zip from Releases and use Install from Disk in Blender's add-on preferences, or run uvx frugal-blender-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/frugal-blender-mcp frugal-blender-mcp.

Configs that use the old blender-astra-mcp or blender-compact-mcp commands keep working.

Architecture
text
AI client -- MCP stdio --> Python bridge -- authenticated loopback JSON --> Blender add-onCLI ----------------------------^                                         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.

Development
bash
uv sync --frozenuv 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.

If this saves your agent some tokens, a ⭐ helps other people find it.

MIT licensed. Independent project, not affiliated with the Blender Foundation or any model provider.

Source: README.md at commit 36c6b10

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestOct 15, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts