OPEN SOURCE DEEP DIVE
MCP for Blender:32 个工具把 Blender 变成 LLM 可直接驱动的 3D 工作台
原名 blender-mcp,第三方社区插件(README 首屏即声明非 Blender 官方出品),MIT,Python,同类 3D MCP 里星标最高的一条。PyPI 包已改名 mcp-for-blender,但 uvx blender-mcp 依然能跑、老配置不用动。架构只有两个组件:Blender 进程内的插件起 socket server 真正执行命令(只有那里有 bpy、当前场景与 UI 线程),独立进程里的 MCP server 做协议翻译,中间是一套 JSON over TCP,默认 localhost:9876。我们数了源码里的 @mcp.tool():32 个,分四层——感知(get_scene_info / get_object_info / get_viewport_screenshot 以 MCP Image 返回,构成改一步看一眼的闭环)、查资料(bpy_api_lookup / describe_node_type,让它查而不是猜 socket 顺序与枚举名)、执行(execute_blender_code 兜底、set_texture、export_scene 出 GLB/FBX)、取与生成资产(Poly Haven 语义检索 + 走 .blend 源文件 + 导入写署名属性、Poly Pizza 约 10600 低模可按真实尺寸落地且 CC-BY 自动写署名、Sketchfab、Hyper3D Rodin 文生/图生 3D、腾讯混元 3D 并区分国内 ai3d 与国际 hunyuan 端点)。安全上任意代码执行是设计而非漏洞:可选 safe mode(BLENDER_MCP_SAFE_MODE=1)执行前静态校验,拦文件读写/子进程/网络/常驻代码,建模渲染保存导入导出照常放行,被拦脚本连原因一起返回给模型让它改写重试。内容遥测默认关闭,另有只能关不能开的 disable_telemetry 工具。29.2k★。我们未在本地跑通 Blender 与该插件,记为待复现。
一句话定位
MCP for Blender(原名 blender-mcp)是第三方社区插件,不是 Blender 官方出品,README 第一屏就写了这句免责声明。它做的事只有一件:把 Blender 变成一个 LLM 可以直接驱动的 3D 工作台——提示词建模、场景搭建、材质灯光、资产检索与导出,全部通过 Model Context Protocol 暴露给 Claude / Cursor / Codex 这类客户端。MIT 协议,Python,星标量级在同类 3D MCP 里排第一。
改名这件事值得单独记一笔:PyPI 包已从 blender-mcp 换成 mcp-for-blender,但 uvx blender-mcp 依然能跑,老配置不用改。对一个已经有几万个安装量的项目来说,「换名而不破坏存量配置」是它工程成熟度的一个侧写。
架构:两个进程,一条 TCP
系统只有两个组件,分工很干净:
| 组件 | 跑在哪 | 职责 |
|---|---|---|
Blender 插件(addon.py) | Blender 进程内 | 在 Blender 里起一个 socket server,接收命令并在 bpy 上下文里真正执行 |
MCP server(src/blender_mcp/server.py) | 独立 Python 进程(或容器) | 实现 MCP 协议,对客户端说 MCP,对插件说 JSON over TCP |
两者之间是一套极简的 JSON 协议:命令是带 type 与可选 params 的对象,响应是带 status 与 result/message 的对象,默认 localhost:9876。这个选择很关键——真正执行代码的地方必须在 Blender 进程里,因为只有那里有 bpy、有当前场景、有 UI 线程。MCP server 只做协议翻译与工具编排。副作用是:Blender 必须开着、插件必须点了 Start MCP Server,并且只能跑一个 MCP server 实例。
32 个工具:真正的设计在这里
我们把 server 源码里的 @mcp.tool() 全数了一遍,是 32 个。它们不是平铺的功能列表,而是分成四层,每层解决一个不同的失败模式:
| 层 | 代表工具 | 解决的问题 |
|---|---|---|
| 感知 | get_scene_info、get_object_info、get_viewport_screenshot | 模型看不见场景就只会盲改。视口截图以 MCP Image 返回,构成「改一步、看一眼」的闭环 |
| 查资料 | bpy_api_lookup、describe_node_type | bpy 的 API 面极大,socket 顺序与枚举名靠模型记忆必然出错;让它查而不是猜 |
| 执行 | execute_blender_code、set_texture、export_scene | 兜底通道:任何专用工具没覆盖的操作,都能落成一段 Python 在 Blender 里跑 |
| 取资产 / 生成资产 | Poly Haven(4 个)、Poly Pizza(3 个)、Sketchfab(4 个)、Hyper3D Rodin(4 个)、Hunyuan3D(4 个) | 模型只会造基础几何体;真实场景需要 CC0 贴图、HDRI、现成模型与 AI 生成的网格 |
第四层是这个项目最被低估的部分。它不是「接了五个资产库」,而是把每个库的使用语义都吃透了:
- Poly Haven(约 2400 个 CC0 资产,免 key、免账号):检索是语义的而非关键词匹配——README 原话是「couch 能找到 sofas,而且任何语言都行」。模型导入走
.blend源文件而不是 glTF/FBX/USD,因为后三者是派生产物、会丢材质细节。HDRI 会被打包进文件并落在一个新的 world 里,不覆盖你已经调好的灯光。导入时把polyhaven_id/url/authors/licence写成对象的 custom property,别人打开这个 .blend 还能追溯到作者。 - Poly Pizza(约 10600 个低模,含被救回来的 Google Poly 档案):每个模型是单个自包含
.glb,几何比 Sketchfab 轻得多,是风格化游戏资产的首选。下载支持normalize_size+target_size直接按真实尺寸落地。目录里约 69% 是 CC-BY,必须署名,所以导入时会把格式化好的署名行写进polypizza_attribution属性里存进文件。 - Hyper3D Rodin / 腾讯混元 3D:文生 3D 与图生 3D,轮询任务状态再导入。混元这块有个真实的坑:国内账号走
ai3d(版本2025-05-13,广州),国际账号走hunyuan(版本2023-09-01,开 PBR,新加坡),用错端点直接AuthFailure.SignatureFailure,所以插件在侧栏留了一个 International (Pro) 开关。
安全:任意代码执行是设计,不是漏洞
execute_blender_code 允许在 Blender 里跑任意 Python。README 用了 Warning 块:强大但危险,生产环境慎用,用之前一定先存档。这是「把专业软件交给模型」这类项目绕不开的核心矛盾——不给任意代码执行,能力就被专用工具的覆盖面卡死;给了,一次幻觉就能毁掉一个做了几十小时的场景。
它的解法是可选的 safe mode(BLENDER_MCP_SAFE_MODE=1):执行前静态校验脚本,拦掉直接读写文件、启动子进程、访问网络、以及安装脚本结束后仍在运行的代码,而建模、材质、渲染、保存、导入导出这些正常工作全部放行。被拦的脚本会连同原因一起返回给模型,让它改写后重试——这一点比单纯的拒绝重要,因为它保住了 agent 的自纠错回路。
遥测是另一处值得学的分寸:内容采集(提示词、生成的代码、视口截图、场景数据、轨迹步骤)默认关闭,要用户在插件偏好里显式勾选;默认只有一份匿名用量记录(安装 ID、会话 ID、工具名、成功与否、耗时、版本、OS、时间戳),而且 DISABLE_TELEMETRY=true 可以连这份也关掉。工具集里还专门给了一个 disable_telemetry,并且只能关不能开——开必须回到 Blender 的 UI 里由人操作。
落地阻力:README 里最诚实的三段
- GUI 客户端不继承终端 PATH:从 Dock/开始菜单启动的 Claude Desktop、Cursor、VS Code 里,
"command": "uvx"会报spawn uvx ENOENT,哪怕终端里uvx好好的。解法是写绝对路径,改完必须完全退出再重启客户端。 - uv 会挑错 Python:装了 conda(自动激活 base)、pyenv、asdf 的机器上,uv 可能选到一个缺 wheel 的解释器。README 直接给了钉死方案:
--python 3.11配UV_PYTHON_PREFERENCE=only-managed。 - 下载会冻住 UI:Poly Haven 资产在 Blender 主线程下载,传完之前界面不响应;分辨率每升一档文件大约翻四倍,所以除非资产怼在镜头前,否则只要 1k/2k。Poly Pizza 的 CDN 在 Cloudflare 机器人防护后面,会挡数据中心、VPN 和云 IP——这种「不是你的 key 坏了」的说明,是被 issue 长期打磨出来的。
在 agientry 里的位置
本站 3D 一档同时收两类东西:一类是生成式资产管线(Tripo、混元 3D、TRELLIS 这些「一句话或一张图出一个网格」),另一类是把专业 DCC 软件接进 agent 回路的桥。MCP for Blender 是第二类里星标最高的那条,而且它同时是第一类的消费者——Rodin 与混元的生成结果就是通过它的工具导进 Blender 的。与 img2threejs(图像直接出 Three.js 场景)的差别也在这里:那条走 Web 渲染栈、产出代码,这条走 Blender、产出 .blend 与 GLB/FBX,面向有真实制作流程的人。用户点名要收 blender-mcp 是对的,它是「agent 能操作专业创作软件」这个命题目前最成熟的开源样本。
本页事实来自项目 README(实读全文)与 src/blender_mcp/server.py 源码(32 个工具逐个核对);星标、协议、语言取自 GitHub API。我们没有在本地跑通 Blender 与该插件,没有做基准或复现测试,safe mode 的静态校验实际能拦到什么程度、截图闭环对多步建模成功率的提升都没有量化,因此这一条记为待复现。