BlenderMCP 完整避坑指南4 步把 Blender 连上 AI附故障排查决策表【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp你有没有过这种经历在对话框里敲下建一个地牢场景Blender 那边纹丝不动转了几十秒最后甩回一个超时BlenderMCP 干的就是这件事——把 Blender 3D 接到你选定的任意大模型上通过 MCPModel Context Protocol一套让 AI 和外部软件对话的标准协议这条通道用大白话指挥它建模、换材质、截视口图。适合想省掉几百次菜单点击的建模师和所有想让工具自己干活的人。先建立 30 秒心智模型谁在跟谁说话整条链路只有三个角色记住它们后面所有配置和排错都是在这三者之间找问题。AI 客户端Claude、Cursor 等发包包但不懂 Blender。MCP 服务端uvx blender-mcp拉起来的那个进程站在 AI 和 Blender 中间的翻译官。AI 说的是意图它负责翻译成 Blender 能执行的 Python干完了再把结果译回去。Blender 插件那个只有单文件的addon.py驻留在 Blender 车间里的工匠真正伸手建物体的就是它。翻译官和工匠之间靠一条专用工单通道TCP socket传话通道号默认9876——翻译官按这个号派单工匠得在这个号上收单错一位都收不到。⚠️ 环境变量就是翻译官的开机工牌进程一启动先扫一遍工牌才决定该往哪台机器、哪个通道号递工单。这也是为什么后面反复强调两边端口必须对得上。想看这条通道的具体实现可以去读服务端源码 src/blender_mcp/server.py 里的BlenderConnection它用一把锁保证工单不乱序工匠这边则看 addon.py面板注册和端口逻辑都在这。BlenderMCP 四步安装清单从装 uv 到第一句指令☐第 1 步装好 uvBlenderMCP 的启动器做什么服务端是 Python 写的uv 负责拉依赖并生成uvx命令。按系统选一条# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh# Windows PowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iexWindows 装完把%USERPROFILE%\.local\bin加进 PATH。⚠️ 别用pip install uv凑数因为它经常不生成uvx后面必踩坑。完成标志新开一个终端uvx --version有版本号输出。☐第 2 步把 AI 客户端指向这个服务做什么以 Claude 桌面版为例打开设置 开发者 编辑配置往claude_desktop_config.json里贴这段——意思是让 Claude 启动时自己拉起翻译官{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }完成标志完全退出并重启 Claude 后工具列表里出现锤子图标——说明 BlenderMCP 工具已挂上。☐第 3 步把插件装进 Blender做什么仓库根目录的addon.py就是全部插件一个文件。Blender 里走编辑 偏好设置 插件 安装...选中它再勾选启用Interface: Blender MCP。完成标志3D 视图按N唤出侧边栏能看到BlenderMCP标签页。☐第 4 步连上发第一句指令做什么在 BlenderMCP 标签页点Connect to Claude状态显示运行中即工匠已就位。回对话框发建一个低多边形场景地牢里一条龙守着一罐金子完成标志Blender 视口自己开始搭东西。 如果第一条指令没反应重发一次就好——那是首次建 socket 连接时的常见现象不是坏了。按场景抄配方只改一处改完就验先把所有能动的旋钮列全固定值那行不用动只供你理解链路变量 / 属性默认什么时候要动它BLENDER_PORT服务端环境变量9876端口被占时例如改9877插件侧边栏的 Port 输入框9876必须跟上BLENDER_PORT一起改BLENDER_HOSTlocalhostBlender 不在本机Docker / WSL / 远程时BLENDER_MCP_DISABLE_TELEMETRY未设置开启匿名统计想彻底关掉就设truesocket 超时服务端内置180 秒改不了只能靠拆小任务绕过场景 AClaude 桌面版标准配置上面第 2 步的 JSON 就是终版。若你机器上有 conda / pyenv 在打架把服务端钉在干净的 Python 3.11 上{ mcpServers: { blender: { command: uvx, args: [--python, 3.11, blender-mcp], env: { UV_PYTHON_PREFERENCE: only-managed } } } }验证重启 Claude发一条简单指令比如建一个立方体视口里有反应、不报编译错。场景 BWindows 下的 Cursor图形界面程序不吃终端 PATH所以要套一层cmd中转{ mcpServers: { blender: { command: cmd, args: [/c, uvx, blender-mcp] } } }macOS / Linux 的 Cursor 用户直接用uvx那版即可。验证Cursor 设置里 MCP 服务显示已连接锤子工具出现。场景 CDocker / WSL / 远程主机原则一句话Blender 要监听在 MCP 进程够得着的位置。给配置加一段envDocker 场景下 host 值按你的网络改env: { BLENDER_HOST: host.docker.internal, BLENDER_PORT: 9876 }WSL2 连 Windows 版 Blender 时优先试BLENDER_HOST127.0.0.1不通再换成 Windows 主机 IP。验证远程跑通后让 AI 截一张视口图——截图走 base64 回传不依赖共享临时目录所以这条路天然支持远程。场景 D命令行一行启动不走配置文件终端里一行搞定CLI 方式接入 Claude Codeclaude mcp add blender uvx blender-mcp验证claude mcp list里能看到 blender 条目且发指令后视口有动作。让它从能动变听话三档进阶第一档给 AI 装上自检闭环连上之后别让它闷头瞎建。流程是发场景指令 → 追加一句截个视口图自己核对一下建得对不对 → 哪不对就说哪不对火把往左挪一点。AI 拿到截图就是拿到了眼睛修正精度完全不一样——这一步不花配置全靠你会不会追问。第二档材质光照的精确控制AI 手里有个execute_blender_code工具能在 Blender 里跑任意 Python这是最细的控制路径。比如把立方体变成金色金属它背后执行的其实就这几行核心逻辑你直接说人话即可不用自己写mat bpy.data.materials.new(Gold) mat.use_nodes True b mat.node_tree.nodes[Principled BSDF].inputs b[Base Color].default_value (0.9, 0.7, 0.1, 1) # 颜色按需求改 b[Metallic].default_value 1.0 b[Roughness].default_value 0.2⚠️ 因为这条工具等于把 Blender 的控制权整体交出去了动手前先保存 .blend 文件——误操作一条就可能毁掉没存的内容。第三档接外部资源库让 AI 现找现用侧边栏 BlenderMCP 面板里勾选对应功能Sketchfab 等需先在编辑 偏好设置 插件 Blender MCP里存好 API Key跨重启不丢然后直接对话Poly Haven用 Poly Haven 的 HDRI、岩石和植被做个海滩氛围——自动搜、下载HDRI 直接设成世界环境光Sketchfab在 Sketchfab 搜一把中世纪椅子并导入支持先看缩略图预览、确认再下载还能按目标尺寸归一化椅子 1 米、桌子 0.75 米Hyper3D Rodin / Hunyuan3D描述一下要的东西生成式建模产出自带材质的模型选型口诀现成具体物件找 Sketchfab通用家具和光环境找 Poly Haven都找不到再上生成式。连不上时照这张表查按你看到的现象走① 现象关键词spawn uvx ENOENT客户端工具直接起不来最可能原因GUI 客户端不继承终端 PATH找不到uvx。which uvxmacOS/Linux或where uvxWindows查出全路径填进配置的command字段Windows 直接套用场景 B 的cmd /c写法改完配置完全退出客户端再重开只关窗口没用 仍不通确认新终端里uvx --version是否真有输出没有就回到四步清单第 1 步重装。② 现象关键词能启动但一直连接超时AI 说够不到 Blender最可能原因工匠没在岗或两边通道号对不上。回 Blender 侧边栏确认显示运行中没有就先点 Connect to Claude核对BLENDER_PORT与插件 Port 输入框是否同一个数检查防火墙有没有放行 9876确认开的是带界面的 Blender——用blender -b后台模式跑命令永远执行不了服务端报错也会点名这一条 仍不通进现象 ⑤。③ 现象关键词命令发出去卡很久、超时、或流式响应错乱最可能原因单条请求太大撞上了 180 秒 socket 超时或两条客户端在抢同一条通道。把大任务拆成几步小指令喂给 AI 一步步做同一时间只挂一个客户端Cursor 和 Claude 别同时开这个 MCP 服务 仍不通重启插件再试还不行走现象 ⑤。④ 现象关键词uvx 反复编译报错、Python 版本冲突最可能原因conda / pyenv 的 Python 与依赖打架Apple Silicon 上还可能被拉去编 x86_64 的包cryptography 报错最典型。配置里写args: [--python, 3.11, blender-mcp]加env: { UV_PYTHON_PREFERENCE: only-managed }Apple Silicon 换成args: [--python, 3.11-aarch64, blender-mcp]仍不通确认 Blender 版本 ≥ 3.0推荐 4.x / 5.x旧版本走不通部分功能。⑤ 现象关键词以上全试过还是不通最可能原因插件或服务端进了脏状态。重启 Blender 插件重启 MCP 客户端把配置里的 blender 服务整个删掉、按第 2 步重新添加 这三步走完绝大多数幽灵问题会消失。还能往哪挖 收尾清单往深走的三个方向想让 AI 每一步都看得见就多让它截图自查想让服务端更安静在 Blender 插件偏好里关掉遥测或直接设BLENDER_MCP_DISABLE_TELEMETRYtrue想读懂通信本质把server.py里BlenderConnection的锁 socket 流实现通读一遍。 升级插件时只需下载新的addon.py替换再把客户端里的 MCP 服务删掉重加一次。收尾前把这几件事勾掉每项 10 分钟内☐ 终端跑uvx --version有输出☐ 客户端 MCP 配置写好重启后出现锤子工具☐ 插件侧边栏点 Connect状态变运行中☐ 发一条建场景指令再要一张截图让 AI 自查☐ 试跑一个外部资源库Poly Haven 最省心☐ 把上面那张排查表存进笔记下次卡住直接对号入座哪一步卡住了带着你的报错原文、客户端类型和系统版本来交流——定位快人一步。【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考