Frugal Blender MCP

io.github.mohakmalviya由 GitHub 帳號 mohakmalviya 發布v0.2.0更新於 Oct 24, 2026

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

已驗證STDIO僅桌面開發者工具媒體與設計

概覽

AI 產生的概覽

節省 token 的 Blender MCP 伺服器，提供 discover、execute、inspect、capture 四個工具，讓代理建構、製作動畫並算圖 3D 場景。

可以做什麼
  • 查詢操作參數契約，並依名稱分頁檢視場景資料
  • 建立與編輯場景：基本幾何體、陣列、變換、材質、燈光、攝影機、刪除
  • 以任意修改器或 RNA 屬性細修，並用關鍵影格與影格做動畫
  • 擷取預覽圖、算圖靜態影像或動畫、儲存 .blend 副本
  • 啟用後可透過同一個 execute 呼叫執行任意 bpy Python 程式碼
適用情境
適合想讓 AI 代理在桌機上創作或修改 Blender 場景，同時盡量壓低固定工具定義所佔上下文的情況，前提是願意執行 Blender 並啟用配套外掛橋接。
執行需求
在桌機上透過 uvx（Python/uv）啟動的本機程序；需要 Blender 4.2+ 並安裝 Frugal Blender MCP 外掛且啟動橋接；橋接僅監聽本機回環位址，每次啟動使用新的隨機權杖；僅在同時執行多個橋接時才需要 BLENDER_COMPACT_CONNECTION。
安裝前請注意
寫入與算圖預設開啟；刪除、儲存與 python 預設關閉，須在外掛面板中開啟，代理無法變更。python 屬於不受限制的本機程式碼執行，僅對可信任的代理開啟。刪除操作需要 confirm: true。擷取、算圖與儲存的檔案會寫入橋接的 exports 資料夾。據稱沒有遙測。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Frugal Blender MCP，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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.

來源：README.md，提交 36c6b10

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.2.0最新Oct 15, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分