如何把 mcp-for-blender 装进 Blender:30 分钟从插件安装到 AI 真的在视口里建模
你在客户端里敲下"建一个低多边形小屋",等了十几秒,弹出一句 spawn uvx ENOENT;换一台客户端再试,Blender 侧边栏还是 "Not connected",指令石沉大海。问题几乎不在你,而在那条链路上三个软件交接的某一环没对上。这篇文章把每一环接上,直到视口里真的冒出物体。
mcp-for-blender 是一个社区插件:让任意大模型(Claude、Cursor、Codex 都行)用自然语言驱动 Blender,建物体、改材质、跑 Python、从素材库拉资源。会开终端就能装完,走完本文,第一条建模指令会真正落进 3D 视口。
先看链路图:装几样东西,谁和谁说话
MCP(Model Context Protocol)是 AI 客户端和外部工具之间的"普通话",两边都按它说话才接得上话。这条链路上有三样东西、两根线:
你
│ 自然语言
▼
AI 客户端(Claude / Cursor / Codex)
│ stdio:客户端为服务开的那根标准管道,指令进去、回执出来
▼
MCP 服务(uvx 一条命令拉起的 mcp-for-blender)
│ socket:两个程序之间传话的线,像一通电话,线号 9876
▼
Blender 插件(addon.py)→ 在 3D 视口里执行建模
| 组件 | 像什么 | 干什么活 |
|---|---|---|
| AI 客户端 | 餐厅的顾客 | 你说话的地方,把话传下去一层 |
| MCP 服务 | 传话的服务员 | 把话翻译成 JSON 指令,递给 Blender |
| 端口 9876 | 桌号 | 两边写同一个号,服务员才找得到桌 |
| Blender 插件 | 后厨的厨师 | 真正动手,在视口里做模型 |
JSON 是键值对文本,指令和回执都靠它装,例如一条建物体指令长这样:{ "type": "create_object", "params": { "type": "CUBE" } }。插件执行完回 status: success,出错则 status: error 并带 message。
一句话原理:线通了,话才通。
由内向外装通
反着常见教程来:先装 Blender 里的插件,再验证中间服务,最后配客户端,最后接通。
先把"听电话的人"装进 Blender
目的:让 Blender 能接到指令。
操作:
- 若没有 uv,先装:macOS 用
brew install uv;Linux 跑 astral.sh 的安装脚本;Windows 用 PowerShell 跑安装脚本,再把%USERPROFILE%\.local\bin加进 PATH,重开终端。 - 一条命令装插件,它会把插件复制进 Blender 的 addons 目录(落盘名
blender_mcp.py),被替换的旧文件留一份.bak:
uvx mcp-for-blender install-addon
命令找不到你的 Blender 时手动装:git clone https://gitcode.com/GitHub_Trending/bl/mcp-for-blender,在 Blender 里 编辑 > 偏好设置 > 插件 > 安装… 选中根目录的 addon.py,再启用 Interface: MCP for Blender。
翻车点:⚠️ 别用 pip install uv 凑数——它经常不生成 uvx 命令,客户端启动那一刻会直接报找不到命令。
过关信号:uvx --version 打印版本号;install-addon 打印落盘路径;3D 视口按 N 键,侧边栏多出一个 MCP for Blender 标签页。
一句话原理:先有听电话的人。
装好中间服务并验证能拉起
目的:确认这台机器一条命令就能把服务拉起来。
操作:跑一次
uvx mcp-for-blender --help
首次运行会下载包,之后再跑就是秒级。
翻车点:⚠️ 机器上有 conda / pyenv 时,别让它拿系统 Python 现编译——缺 wheel 会一路编译报错。修法:客户端配置里写 "args": ["--python", "3.11", "mcp-for-blender"],并加 "env": { "UV_PYTHON_PREFERENCE": "only-managed" }。
过关信号:--help 打印出用法说明,里面看得到 install-addon 这个选项。
一句话原理:服务能拉起,客户端就不慌。
让客户端启动时自动拉起服务
目的:客户端一开,服务自己跟上来。
操作:打开 Claude 桌面版 设置 > 开发者 > 编辑配置,在 claude_desktop_config.json 里贴入:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["mcp-for-blender"]
}
}
}
包名是 mcp-for-blender(旧的 blender-mcp 也能跑,新装请用新名)。Cursor / VS Code / Codex 同理,都是一条 uvx 命令拉起服务。
翻车点:⚠️ 改完配置别只保存就接着用——这份文件只在客户端启动那一刻读一次,不彻底退出重开等于没改。也⚠️ 别同时让两个客户端挂这个服务——两边共用一根 socket 线,回执会串台。
过关信号:彻底退出客户端再重开,工具列表里出现 blender 条目,条目旁有锤子图标。
一句话原理:客户端只管把服务叫醒。
接通:在侧边栏按下按钮
目的:插件开始监听 9876,指令有回音。
操作:3D 视口按 N,打开 MCP for Blender 标签页,勾选需要的资源库(Poly Haven 免密钥),Port 保持 9876,点 Start MCP Server。
翻车点:⚠️ 别把 9876 端口直接暴露到公网——插件这根 socket 没有认证和加密,任何够得到这个端口的人都能在你的 Blender 里跑 Python;跨机器请保持 localhost + SSH 隧道。
过关信号:面板从 "Not connected" 变成 "Connected on port 9876"。
一句话原理:两端同号,线就通。
第一条指令验收
给客户端发这句:
"创建一个低多边形地牢:火把、石柱、一扇铁门。"
预期现象:视口开始冒物体。
已知坑:第一条指令偶尔没反应,原样重发一次——插件是首条命令到达时才真正建立 socket 通道,第一次超时是已知行为,不是故障。
三条信号齐了才算跑通:
- 面板显示 "Connected on port 9876"
- 视口里出现新物体
- 客户端的回执里有
status: success
翻车自救:先分诊,再修
按现象定层,走对应的线:
| 你看到什么 | 走哪条线 |
|---|---|
| 客户端起不来,报 ENOENT | 客户端层 |
| 服务起来了,连 Blender 一直超时 | 服务层 |
| 简单指令正常,复杂请求卡住 | 应用层 |
客户端层:服务根本起不来
看到这段字就跳到这里:
failed to start: spawn uvx ENOENT
修法:终端里 which uvx(macOS/Linux)或 where uvx(Windows)拿到绝对路径,把路径填进 "command"。图形界面客户端不继承终端 PATH,这正是"终端里明明能跑"却 ENOENT 的根因。 兜底:重装 uv,uvx --version 重新确认。
服务层:连不上 Blender,一直超时
看到这段字就跳到这里:
Timeout waiting for Blender response - try simplifying your request. If Blender is running headless (blender -b), commands never execute; run Blender with a GUI or via 'xvfb-run -a blender' instead
修法:回 Blender 侧边栏确认面板不是 "Not connected";如果 Blender 是 blender -b 后台模式启动的,命令永远执行不了,换成 GUI 或 xvfb-run -a blender。 兜底:核对插件面板 Port 与客户端 BLENDER_PORT 或 --port(两边都应是 9876),不一致就侧边栏断开重连。
应用层:复杂请求卡住
现象:简单指令有回音,任务一大就超时。
修法:把大任务拆成小指令分步发——单次 socket 请求有 180 秒超时上限;同时确认没有两个客户端在共用这条线。 兜底:侧边栏断开重连;仍卡住就重启 Blender。
三层都查过仍不行
最小复位:① Blender 侧边栏断开重连;② 彻底退出 MCP 客户端重启;③ 把配置里的 blender 服务删掉重新添加。这一套覆盖九成"幽灵问题"。
进阶三关
关卡一:一句话建场景,AI 截图自查
通过标准:AI 能根据视口截图说出场景里有什么,并修正你指出的一处错误。
- 确认面板显示 "Connected on port 9876"
- 发送"创建一个低多边形地牢:火把、石柱、一扇铁门"
- 追加"用视口截图确认一下场景状态"
- 哪里不对就说"把火把往左挪一点",让它再截图核对
⚠️ 别把长串多步任务塞进一句话——单条线 180 秒超时,大任务一口吞必断线。
一句话原理:改完回头看,建模成闭环。
关卡二:跑任意 Python,把立方体变金色金属
通过标准:材质面板里 Principled BSDF 节点 Metallic 为 1、Roughness 为 0.2。
- 先保存当前文件
- 让 AI 新建一个立方体
- 发送"把这个立方体变成金色金属材质,粗糙度 0.2"
- 切到材质面板核对节点参数
⚠️ 别让 AI 在未保存的场景上跑 execute_blender_code——这个工具能执行任意 Python,等于把 Blender 窗口交给 AI 操作,翻车时保存文件是唯一的后悔药。
一句话原理:工具放开,风险也放开。
关卡三:Poly Haven 管道铺海滩,再导出 GLB
通过标准:世界环境变成 HDRI 光照,场景出现岩石和植被物体,最后拿到一个能打开的 .glb 文件。
- 侧边栏勾选 Poly Haven(免密钥、无账号,CC0 素材)
- 发送"用 Poly Haven 的 HDRI、岩石和植被做个海滩氛围"
- 检查世界环境节点和新增物体
- 追加"把当前场景导出为 GLB",用
export_scene拿到文件
⚠️ 别给离镜头远的素材拉 4k——下载跑在 Blender 主线程上,UI 会卡住直到下完;分辨率每上一档体积约翻四倍,远的用 1k 或 2k 就够。
一句话原理:搜索下载应用,全程不碰网页。
源码往哪看,今天做什么
三个入口:
- src/blender_mcp/server.py:看
BlenderConnection类如何用锁加 socket 流保证命令不乱序 - addon.py:面板、端口逻辑和
type路由分发,全在这一个文件里 - README.md:Environment Variables 与 Troubleshooting 两节,官方排错的最终依据
今日清单:
- ☐
uvx --version打印出版本号 - ☐ 插件装好,3D 视口按
N出现 MCP for Blender 标签页 - ☐ 客户端配置写好并重启,工具列表出现 blender 条目
- ☐ 面板显示 "Connected on port 9876",第一条指令有回音
- ☐ 勾选 Poly Haven,拉进一张 HDRI
- ☐ 用
export_scene导出一个 GLB
卡住时带三样东西来问:报错原文、操作系统版本、客户端类型。三样齐,定位最快。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考





