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 分