MCP for Blender 完整安装指南用自然语言驱动 Blender 建模【免费下载链接】mcp-for-blenderCommunity plugin to control Blender 3D with any LLM of your choice. Not affiliated with the official Blender Foundation.项目地址: https://gitcode.com/GitHub_Trending/bl/mcp-for-blender你在对话框里输入建一个低多边形小屋十几秒后视口里真的长出一间小屋——门窗齐活还能追加一句屋顶改成红色它照做。这不是演示视频而是MCP for Blender这条链路在本地跑通后的真实效果。它是一个开源插件让任意大模型Claude、Cursor、Codex 皆可通过自然语言直接操作 Blender建物体、改材质、执行 Python、从素材库拉资源。装好之后你所有的建模操作都只剩说一句话。整条链路由三样东西组成uvx拉起的mcp-for-blender服务端、Blender 里的插件addon.py、两端对齐的 9876 端口。本文按装好 → 接通 → 实战 → 调参 → 排错的顺序走完整条路每一步都给出可观察的验证信号卡住的地方都能对号入座。动手前先看你买到什么先确认这套链路的能力边界装之前知道自己能要什么能力你能对 AI 说什么场景与物体信息现在场景里都有什么创建 / 修改 / 删除物体建一个低多边形地牢把火把往左挪材质控制把它变成金色金属粗糙度 0.2任意 Python 执行工具名execute_blender_code直接写bpy导出 GLB / FBX把场景导出为 GLB工具名export_scenePoly Haven 素材免密钥CC0 的 HDRI、纹理、模型约 2400 个Sketchfab / Poly Pizza 模型需要各自的 API Key可持久存到插件偏好AI 生成 3D 模型Hyper3D Rodin、Hunyuan3D 等生成管道bpy API 参考bpy_api_lookup、describe_node_type查参数不再靠猜上图是 Codex 插件形态视口直接嵌在聊天侧边栏点击场景里的物体即可附加到下一条消息。其他客户端没有这个面板但说一句话 → 视口里出东西的核心体验完全一样。原理一条信号链路上的四个角色[ AI 客户端 Claude/Cursor/Codex ] ⇄stdio⇄ [ MCP 服务端 mcp-for-blender ] ⇄TCP:9876⇄ [ Blender 插件 addon.py ]组件你可以把它理解成一句话职责AI 客户端遥控器你说话的地方只负责发红外信号MCP 服务端信号中枢把自然语言拆成一条条 JSON 指令转给 Blender端口 9876墙上的出线口两端插到同一个插座才通Blender 插件功放 喇叭在 Blender 内部真正执行建模动作MCP 协议就是遥控器和信号中枢共同遵守的信号格式命令和回执都是 JSON长这样{ type: create_object, params: { type: CUBE } }插件执行后回{ status: success, result: ... }出错则status为error并带message。你和视口之间流动的一切载体都是这种 JSON。一句话提炼MCP for Blender 把说话翻译成 Blender 能执行的 JSON 指令再走一条 9876 端口的 socket 落到插件手里。安装第一步装 uv拿到 uvx 启动器uvx是 uv 附带的一次性拉起工具客户端就是靠它启动 MCP 服务端。三个平台的装法# macOS brew install uv # Linux装完落到 ~/.local/bin重开终端才会进 PATH curl -LsSf https://astral.sh/uv/install.sh | sh# Windows装完把 %USERPROFILE%\.local\bin 加进用户 PATH再重开终端 powershell -c irm https://astral.sh/uv/install.ps1 | iex⚠️ 现象终端里能跑uvx客户端却报找不到命令。原因用了pip install uv凑数它经常不生成全局uvx还会把 uv 藏进客户端看不到的环境里。规避一律用上面的官方安装脚本装完终端执行uvx --version打印出版本号才算过关。验证新开一个终端uvx --version有版本号输出。安装第二步把客户端接上 mcp-for-blender 服务以 Claude Desktop 为例设置 → 开发者 → 编辑配置往claude_desktop_config.json里贴入{ mcpServers: { blender: { command: uvx, args: [mcp-for-blender] } } }Cursor、VS Code、Codex 同理都是一条 uvx 命令拉起服务。注意包名是mcp-for-blender旧的uvx blender-mcp也能跑但新装请用新名。⚠️ 现象改完配置没有反应。原因客户端只在启动那一刻读一次这个文件。规避彻底退出再重开——Windows 从系统托盘退出不是关窗口macOS 按CmdQ。⚠️ 现象两个客户端同时挂着服务响应互相错乱。原因两个客户端共用一条 socket。规避同一时间只保留一个客户端挂这个服务。验证重启后工具列表里出现 blender 条目条目旁有锤子图标。安装第三步把插件装进 Blender一条命令推荐uvx mcp-for-blender install-addon它会把插件复制进 Blender 的 addons 目录存为blender_mcp.py被替换的旧文件留.bak备份并打印落盘位置。更省事的方式是uvx mcp-for-blender setup一步装 uv、配好你机器上检测到的客户端、装并启用插件且只追加blender条目、给每个改动过的文件留.bak。如果命令找不到你的 Blender就手动装克隆仓库git clone https://gitcode.com/GitHub_Trending/bl/mcp-for-blender在 Blender 里编辑 → 偏好设置 → 插件 → 安装…选中根目录的addon.py整个插件就这一个文件然后启用Interface: MCP for Blender。验证3D 视口按N键侧边栏出现MCP for Blender标签页。接通 9876发出第一条指令在侧边栏MCP for Blender标签里按需勾选资源库复选框比如 Poly Haven免密钥无账号Port 保持默认9876点Connect to MCP server。⚠️ 现象第一条指令没反应。原因插件在首条命令到达时才真正建立 socket 通道。规避直接重发一次第一次超时是已知行为不是故障。验证面板从 Not connected 变成 Connected on port 9876客户端里发一句创建一个低多边形地牢要有火把和石柱视口开始冒物体。三个信号齐了这条链路就算跑通。一句话提炼服务端负责听懂插件负责照做中间只靠一个两端一致的端口对上号。场景一搭个场景让 AI 自己回头看验证标准AI 能根据视口截图说出场景里有什么并按你的指认修正。确认面板显示 Connected on port 9876发送建一个低多边形地牢火把、石柱、一扇铁门追加用视口截图确认一下场景状态哪里不对就说把火把往左挪一点让它再截图核对原理提炼AI 改完会回头看视口建模从盲改变成了操作 → 截图 → 修正的闭环。场景二跑 Python把立方体变成金色金属验证标准材质面板里 Principled BSDF 节点的 Metallic 为 1、Roughness 为 0.2。⚠️ 现象执行execute_blender_code后场景被改到无法回退。原因这个工具能执行任意 Python等于把 Blender 控制权整个交给 AI。规避动手前先保存文件这是铁律翻车时唯一的后悔药。保存当前文件让 AI 新建一个立方体发送把这个立方体变成金色金属材质粗糙度 0.2切到材质面板核对节点参数原理提炼工具层之外还能直接写bpy代码自由度没有上限风险也没有上限。场景三用 Poly Haven 铺一个海滩再导出 GLB验证标准世界环境变成 HDRI 光照场景里出现岩石和植被物体本地拿到一个可打开的.glb文件。⚠️ 现象下载素材时 Blender 界面卡死。原因素材下载走 Blender 主线程UI 会停到下载完成。规避让它按 1k 或 2k 分辨率拉取——分辨率每上一档体积大约翻四倍离镜头远的素材别贪 4k。侧边栏勾选Poly Haven免密钥、无账号CC0 免费素材发送用 Poly Haven 的 HDRI、岩石和植被做个海滩氛围检查世界环境节点和新增物体追加把当前场景导出为 GLB用export_scene拿到文件给下游用原理提炼插件内置了成套资源管道搜索、下载、应用一条龙AI 不用碰任何网页。参数调优默认值、换端口、跨机器、钉 Python、关遥测先对号入座你遇到的情况看哪小节不想改只要默认行为默认值一览9876 端口被占或要开两个 Blender换端口的最快做法服务端跑在 Docker / 另一台机器跨机器连接怎么配uvx 起服务报编译 / Python 冲突钉死 Python 版本不想上报任何统计关掉遥测默认值一览触发条件什么都不改直接跑。BLENDER_HOST默认localhost服务端只找本机的 BlenderBLENDER_PORT默认9876插件面板 Port 输入框默认也是 9876单次 socket 请求超时上限 180 秒遥测默认只收集一条最小匿名用量记录你的提示词、代码、截图默认不收集除非你明确勾选同意验证保持默认装通即可无需任何操作。换端口的最快做法触发条件9876 被别的程序占了或你同时开两个 Blender 实例。改法客户端配置env里加BLENDER_PORT: 9877或直接用 CLI 参数args: [mcp-for-blender, --port, 9877]参数优先于环境变量同时把插件面板 Port 改成同一个号。验证两边都重连面板显示 Connected on port 9877指令有回音。⚠️ 现象改了客户端面板还是连不上。原因只改了一边等于对着一个空插座找线。规避两端必须一致。跨机器连接怎么配触发条件MCP 服务端跑在 Docker 里或另一台机器上。改法仓库自带 Dockerfile镜像默认BLENDER_HOSThost.docker.internalmacOS / Windows 的 Docker Desktop 开箱可达宿主机的 BlenderLinux 上该域名不存在改用 host 网络{ command: docker, args: [run, -i, --rm, --networkhost, -e, BLENDER_HOSTlocalhost, mcp-for-blender] }验证视口截图能正常返回——截图走 base64 回传不依赖共享目录远程也能用。⚠️ 现象端口暴露后陌生请求能操作你的 Blender。原因插件的 socket 没有认证和加密任何够得到这个端口的人都能在你的 Blender 里跑 Python。规避跨机器保持 localhost SSH 隧道别把端口直接暴露到网络。钉死 Python 版本触发条件机器上有 conda / pyenv或新 CPython 没有现成 wheeluvx 拉起服务时各种编译报错。改法{ command: uvx, args: [--python, 3.11, mcp-for-blender], env: { UV_PYTHON_PREFERENCE: only-managed } }UV_PYTHON_PREFERENCEonly-managed让 uv 不去碰 conda、pyenv、系统 Python。仍怀疑旧缓存捣乱就清掉重拉uv cache clean mcp-for-blender blender-mcp uvx --refresh mcp-for-blender验证客户端不再刷编译错误锤子图标正常出现。关掉遥测触发条件你连那条最小匿名用量记录都不想发。改法终端export DISABLE_TELEMETRYtrue后再启动或写进客户端配置的envDISABLE_TELEMETRY: true。验证服务端不再有任何上报功能完全不受影响。一句话提炼默认值已经能让本地跑通所有变量都围绕两端号码一致和服务端选对的 Python这两件事。排错先定位再动手先对号入座你看到的现象走哪条链客户端起不来报 spawn 错误故障链 1服务起来了连 Blender 超时故障链 2简单指令正常、复杂请求超时或卡住故障链 3以上都试过了故障链 4故障链 1客户端根本起不来报错原文CtrlF 对号入座failed to start: spawn uvx ENOENT终端执行which uvxmacOS/Linux或where uvxWindows→ 预期打印出完整路径把绝对路径填进commandWindows 也可用command: cmd, args: [/c, uvx, mcp-for-blender]→ 预期配置指向绝对路径。原因一句话图形界面客户端不继承终端 PATH这就是终端里明明能跑却 ENOENT 的全部原因彻底退出客户端再重启 → 预期工具列表出现 blender 条目兜底重装 uvuvx --version重新确认。故障链 2连不上 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 → 预期能看到 Connected on port …核对插件面板 Port 与BLENDER_PORT/--port→ 预期两边数字一致确认 Blender 是带界面启动的blender -b后台模式下命令永远执行不了→ 预期指令有回音兜底侧边栏 Disconnect 再重连端口再核一遍。故障链 3复杂请求超时或卡住触发条件简单指令正常复杂请求超时或多个命令挤在一条 socket 上串线。把大任务拆成小指令分步发单次上限 180 秒→ 预期每步都有回执检查是否 Cursor 和 Claude 同时挂着 MCP 服务 → 预期同一时间只保留一个客户端侧边栏断开重连重建连接 → 预期后续命令恢复正常兜底继续简化请求或重启 Blender。故障链 4终极三板斧重启 Blender 插件Disconnect → Connect to MCP server彻底重启 MCP 客户端把配置里的 blender 服务删掉重新添加这一套基本覆盖九成幽灵问题。一句话提炼九成故障都发生在遥控器没连上信号中枢或出线口号码没对上先验证两端状态再动别的。继续深挖源码入口与今天就能做完的事三个可以顺着挖的入口src/blender_mcp/server.pyBlenderConnection类锁加 socket 流保证命令不串线addon.py面板、端口监听和type命令路由全在这个文件里README.mdEnvironment Variables 与 Troubleshooting 两节官方排错的最终依据Dockerfile跨机器部署的起点镜像里默认BLENDER_HOSThost.docker.internal今天 10 分钟做完这几件事☐ 终端验证uvx --version有版本号输出☐ 写好客户端 MCP 配置并彻底重启确认锤子图标出现☐uvx mcp-for-blender install-addon装好插件面板显示 Connected on port 9876☐ 让 AI 建一个小场景并用视口截图自查一轮☐ 勾选 Poly Haven完成一次 HDRI 或模型导入☐ 用export_scene把场景导出成 GLB哪一步卡住了直接带报错原文、操作系统版本、客户端类型三样来找——这三样齐了定位最快。【免费下载链接】mcp-for-blenderCommunity plugin to control Blender 3D with any LLM of your choice. Not affiliated with the official Blender Foundation.项目地址: https://gitcode.com/GitHub_Trending/bl/mcp-for-blender创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考