blender-mcp

一个构建 Blender .blend 文件的 MCP 服务器。它通过两种方式与 Blender 交互：

• Headless（无头模式） — 每次调用都会启动一个全新的 blender --background 进程。具有确定性、始终可用，是生成文件的正确选择。

• Live（实时模式） — 一个小型 Blender 插件打开一个本地端口，服务器可以驱动你已经打开的 Blender 窗口，你可以实时观看操作过程。

两种方式运行相同的处理代码，因此脚本的行为完全一致。本地 Web UI 允许你上传参考图像，并使用相同的工具运行生成任务。

系统要求

Related MCP server: Blender MCP

设置

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

如果跳过 .env，服务器会在你的 PATH 以及每个驱动器上的标准 Program Files/Blender Foundation/Blender <version> 文件夹中搜索，并优先选择找到的最新版本。

启用实时桥接

插件已安装但处于空闲状态，直到你启动它：

1. 打开 Blender。

2. 在 3D 视口中按 N 键显示侧边栏。

3. 打开 MCP 选项卡，然后点击 Start MCP Bridge。

在插件偏好设置中勾选 Start listening on launch 可省去每次手动启动的步骤。

连接 MCP 客户端

.cursor/mcp.json 已为本项目注册了该服务器。若要使其全局可用，请将该块复制到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

质量工作流

生成质量来自于观察，而不是单一的脚本转储：

1. list_references / view_reference — 首先打开参考图像

2. 使用 studio 或 product 模板调用 create_blend

3. 通过小的 run_script 步骤构建；使用 apply_material 处理金属/塑料/橡胶/玻璃/木材

4. preview_views — 多角度 EEVEE 预览；通过 view_image 与参考图像对比

5. 修复，再次预览

6. 最终 render / render_and_view（最终渲染使用 CYCLES；迭代时使用 EEVEE）

本地 Web UI

uv run blender-mcp-web
# open http://127.0.0.1:8765

上传参考图像，输入提示词，并在 output/jobs/ 下浏览任务。

• 如果在 .env 中设置了 BLENDER_MCP_LLM_API_KEY — 该网站会运行一个受限的多模态代理，调用相同的 Blender 工具（通过 BLENDER_MCP_LLM_PROVIDER 支持 OpenAI 兼容或 Anthropic 接口）。

• 如果没有设置密钥 — 上传和任务页面仍然可用；在 Cursor 中打开任务，并要求 MCP 代理从 output/jobs/<id>/refs 构建。

工具

编写脚本

run_script 和 create_blend 的 script 参数在一个命名空间中执行，其中已绑定 bpy、mathutils、math、D（bpy.data）和 C（bpy.context）。通过赋值给 result 或调用 emit(value) 将数据传回。

模板

目录结构

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

测试

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

注意事项与限制

• run_script 在 Blender 内部执行任意 Python 代码。请将桥接保持在本地回环地址上。

• 长时间渲染会阻塞实时 UI，直到渲染完成。

• viewport_screenshot 仅适用于实时模式。

• Cycles 默认使用 CPU，除非你在 Blender 偏好设置中启用 GPU 设备。

• Web 代理需要支持工具调用和图像的多模态模型。

许可证

MIT