BlenderMCP 实战教程：让 AI 接管 Blender 建模的完整步骤与连接失败避坑指南

BlenderMCP 实战教程：让 AI 接管 Blender 建模的完整步骤与连接失败避坑指南

【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp

BlenderMCP 是一个让任意大模型直接操控 Blender 3D 的开源桥梁：你说一句"建个低多边形地牢，中间放一条龙"，它就在 Blender 里真的建出来——建模、改材质、布光、视口截图，全部靠对话完成。这篇文章先把它拆成三块讲清楚各自职责，再给你每一步能直接抄的配置，最后按"先定位、再动手"的思路整理一份断连救援表，全程不留暗坑。

BlenderMCP 的完整链路：三个部件各自在干什么

整条链路长这样：

AI 客户端（Claude / Cursor）← MCP 协议 → blender-mcp 服务端 ← TCP:9876 → Blender 插件（addon.py）

• AI 客户端：你输入自然语言的地方。它自己不碰 Blender，只负责把话转给服务端。
• blender-mcp 服务端：用uvx blender-mcp拉起的"翻译官"，把 AI 的意图翻译成发给 Blender 的 JSON 指令，再把结果传回来。注意它不需要你手动挂着——客户端启动时会自动拉起它，这是很多人多此一举手动常驻、反而觉得它"卡死"的根源。
• Blender 插件（addon.py）：住在 Blender 内部的"手"，负责真正建物体、改节点、截视口图。

三块之间靠一根 TCP 连接，默认端口 9876。这里有个必须刻进肌肉记忆的要点：端口是两侧各填一次的——服务端读环境变量BLENDER_PORT，插件端读侧边栏里的 Port 输入框。两边数字不一致，表现就是标准的"连接超时"。

如何把两端接起来：四步装通 BlenderMCP

第一步：装好 uvx 这个启动开关

服务端靠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 | iex"

Windows 装完需把%USERPROFILE%\.local\bin加入 PATH 并重启终端。⚠️ 别用pip install uv凑合，它往往不会生成uvx命令，后面所有配置都会卡在第一步。

第二步：告诉 AI 客户端服务端在哪

以 Claude 桌面版为例，路径是设置 > 开发者 > 编辑配置（claude_desktop_config.json），贴上：

{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } }

改完必须完全退出客户端再重开，热切换读不到新配置。

两个高频变体：

• Windows 上的 Cursor / 任何 GUI 客户端：图形界面程序启动时看不到你在终端里配的 PATH，直接写"command": "uvx"会报spawn uvx ENOENT。改走cmd转发：

{ "mcpServers": { "blender": { "command": "cmd", "args": ["/c", "uvx", "blender-mcp"] } } }

• 机器上有 conda / pyenv 导致 Python 打架：给服务端钉死解释器版本：

{ "mcpServers": { "blender": { "command": "uvx", "args": ["--python", "3.11", "blender-mcp"], "env": { "UV_PYTHON_PREFERENCE": "only-managed" } } } }

第三步：把插件装进 Blender 并点 Connect

1. 拿到仓库根目录的 addon.py——整个插件就这一个文件
2. Blender 里编辑 > 偏好设置 > 插件 > 安装...，选中它
3. 勾选启用"Interface: Blender MCP"
4. 在 3D 视图按N唤出侧边栏，切到BlenderMCP标签，确认端口填的是 9876
5. 点Connect to Claude，面板显示"运行中"即插件端就绪

第四步：发出第一句话，确认链路通了

回客户端发一条："创建一个低多边形地牢，有火把、石柱和一扇铁门"。对话区出现锤子图标、Blender 视口开始自己动，说明全链路打通。💡 第一条指令偶尔石沉大海是首连 socket 的常见现象，原样重发一次通常就好了。

如何配对环境变量：BLENDER_HOST、BLENDER_PORT 与遥测开关

环境变量是服务端的"出厂设定"，进程启动时读一次，决定它往哪台机器、哪个端口拨号：

容器、WSL、远程部署下怎么配

关键原则只有一条：Blender 得监听在 MCP 进程够得着的位置。在客户端配置里加env：

"env": { "BLENDER_HOST": "host.docker.internal", "BLENDER_PORT": "9876" }

WSL2 连 Windows 侧的 Blender 时优先试BLENDER_HOST=127.0.0.1，不通再换 Windows 主机 IP。视口截图是以 base64 编码回传的，不依赖双方共享临时目录，所以远程场景下"让 AI 看图自查"依然可用。

命令行如何直接启动 blender-mcp 服务

不走配置文件的话，Claude Code CLI 一行注册：

claude mcp add blender uvx blender-mcp

也可以手动打好环境变量再启动（调试时用）：

export BLENDER_HOST='localhost' export BLENDER_PORT=9876 export BLENDER_MCP_DISABLE_TELEMETRY='true' uvx blender-mcp

三个实操细节：

• 别把uvx blender-mcp当常驻进程手动跑。它静默等待客户端连接时看起来像挂住，按Ctrl-C即可退出。
• 嫌版本不更新：uv cache clean blender-mcp && uvx --refresh blender-mcp，清缓存再刷新。
• 完全不想用 uv 的话，pipx install blender-mcp是等价替代。

接上之后能干什么：四类常见诉求的玩法

一句话建场景，并让 AI 自己截图核对

这是最推荐的闭环：先下指令（"低多边形地牢，火把、石柱、铁门"），等模型出来后追一句"用截图确认一下场景状态"。这会触发视口截图工具，AI 能"亲眼"看到建出来的东西，你再一句"把火把往左挪一点"，它就是基于截图和场景信息做修正，而不是盲改。

如何精确控制材质与光照

AI 可以通过execute_blender_code在 Blender 内执行任意 Python，这是材质控制最细的路径——比如"把这个立方体变成金色金属"，它会直接操作节点树（新建 Principled BSDF、调 Base Color / Metallic / Roughness、赋给对象）。⚠️ 这条工具等于把 Blender 的控制权整个交给 AI，动手前先保存文件是铁律。

外部资源怎么调：Poly Haven、Sketchfab 与生成式模型

在侧边栏 BlenderMCP 面板勾选对应功能、对话中直接指挥即可：

• Poly Haven：让 AI"用 Poly Haven 的 HDRI、岩石和植被做海滩氛围"，它自动搜索并下载，HDRI 会直接设为世界环境。
• Sketchfab：在插件偏好里填好 API Key 后，可以"搜一把中世纪椅子并导入"，支持缩略图预览、确认后下载、按目标尺寸归一化。
• Hyper3D Rodin / Hunyuan3D：描述需求生成自带材质的定制模型再导入场景。

选型口诀：现成具体物件先查 Sketchfab，通用家具和氛围光走 Poly Haven，库里都没有的定制需求才用生成式。

连接失败救援表：先看信号，再动手修

按"症状 → 卡在哪 → 怎么修"排好序，遇到对号入座：

源码入口在哪里，如何升级

• 想看"命令为什么不会乱序"：src/blender_mcp/server.py 里的BlenderConnection，一把锁把发送+接收串起来，保证第二条指令的响应不会被误读成第一条的。
• 想看插件端面板注册与端口逻辑：addon.py。
• 升级流程两步：下载最新版addon.py替换旧文件；在客户端配置里删掉 blender 服务再重新添加一次。

记住这条主线就够用了：客户端管说话，uvx blender-mcp管翻译，addon.py管动手，9876 两边必须一致——链路里任何一块错位，表现都逃不出上面那张救援表。

【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp