BlenderMCP 配置完整实战：从零跑通 AI 指挥 Blender，讲清每一项配置与高频坑
【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp
你可能也遇到过这种场面：Blender 刚装好，AI 客户端里加上了 MCP 配置，第一条指令发出去，对面要么"连接超时"，要么干脆没声。教程只说"装个插件就行"，可端口号、环境变量、Blender 右侧那个小面板，它们之间要怎么对上，没人讲。BlenderMCP 是一个把 Blender 3D 接到任意大模型的开源插件，走的是模型上下文协议（MCP）这条标准通道，让你用自然语言建物体、改材质、截视口图。下面咱们从装 uv 开始，先把线接通，再逐个拆开这些配置，说明它们各管什么、什么时候才需要动。刚接触 BlenderMCP，或者机器上卡住没定位出原因的，照着往下走就行。
一条电话线两头：BlenderMCP 三方协作的原理
动手改配置之前，先建立一个心智模型。整套系统由三块组成，数据是单向流动再回来的：
- AI 客户端（Claude Desktop、Cursor 等）——打电话的人
- MCP 服务端（
blender-mcp这个 Python 包）——中间的话务员 - Blender 插件（一个文件 addon.py）——真正动手的工匠
你输入一句话，模型先把它翻译成一次工具调用（比如"建一个球"），MCP 服务端收到后，把请求包成 JSON，从一条 TCP 套接字发出去。这条套接字就是电话线，默认拨向的端口号是9876——端口号就是门牌号，线路两端各拿着同一个门牌号，电话才接得上。插件端守在门牌号后面，收到报文后在 Blender 里实际操作场景，结果再顺着同一条线回来。
MCP 协议本身可以想成一张"标准工单格式"：客户端和任何 MCP 服务端都认同一张单子，所以同一份blender-mcp配置，Claude 和 Cursor 都能用。
💡 服务端自己不建模，它只负责把"模型说的话"翻译成"Blender 能执行的动作"。建物体、截图、下载资源这些真正的逻辑，全在插件那端。
五步把 AI 和 Blender 接通：从装 uv 到第一条指令
以下以 Claude Desktop 为例，假设全都在一台机器上，照着抄就能跑通。前提版本：Blender 3.0 及以上（推荐 4.x），Python 3.10 及以上。
第 1 步：装好 uv
uv是 Python 服务端的启动器兼快递员，负责把blender-mcp这个包取回来、装进一个隔离的运行环境。按系统装：
# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh装完重启终端，验证快递员就位：
uvx --version # 能打印出版本号才算 OK⚠️ 别用pip install uv凑合——它经常不生成uvx命令，第 2 步会直接卡住。
第 2 步：写客户端配置
Claude Desktop 走设置 > 开发者 > 编辑配置，在claude_desktop_config.json里加上：
{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"] } } }这段配置的意思是：Claude 启动时，让uvx负责拉取并运行blender-mcp服务，全程在后台。写完完全退出 Claude 再重开，让它重新读配置。
第 3 步：把插件装进 Blender
插件就是仓库根目录这一个文件 addon.py，没有别的依赖。如果你还没拿到仓库：
git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp # 克隆仓库，取根目录的 addon.py然后在 Blender 里：编辑 > 偏好设置 > 插件，点安装...选中addon.py，在列表里勾选"Interface: Blender MCP"启用它。
第 4 步：接通连接
在 3D 视图按N键唤出侧边栏，切到BlenderMCP标签，点Connect to Claude。面板上出现Running on port 9876字样，说明插件端已经在门牌号后面守着了。
第 5 步：发出第一条指令
在客户端里输入："创建一个低多边形地牢场景，里面有火把、石柱和一扇铁门"。视口开始"自己动起来"、客户端里出现锤子图标，说明这条线已经通了。
💡 第一条指令偶尔没反应是正常现象——插件首次要建立 socket 连接，重发一次通常就好。
BlenderMCP 配置速查：端口、主机地址与遥测开关
所有能调的旋钮不多，大多是环境变量。环境变量可以想成贴在进程前面的便签：服务端启动时先看便签，才知道该往哪扇门上拨号。两个关键的BLENDER_HOST和BLENDER_PORT就是在服务端启动时读取的，读配置的代码在 src/blender_mcp/server.py 里，不神秘。
| 配置项 | 默认值 | 作用 | 何时需要改 |
|---|---|---|---|
BLENDER_HOST | localhost | 服务端拨号去找插件的主机地址 | Blender 在容器 / 远程机器上时 |
BLENDER_PORT | 9876 | 服务端拨的端口号 | 9876 被别的服务占用时 |
| 插件端 Port 输入框 | 9876 | 插件监听的端口号 | 必须与BLENDER_PORT保持一致 |
BLENDER_MCP_DISABLE_TELEMETRY | 未设置（遥测开启） | 关闭匿名使用统计 | 不想上报任何使用数据时 |
唯一要记死的规则：服务端的端口和插件面板里的端口必须对得上。一边 9876、另一边 9877，就是"你在 5 楼等人，人家在 3 楼等你"，永远连不上。
场景一：桌面端全部同机，就不必改任何配置
AI 客户端、MCP 服务端、Blender 都在同一台物理机上时，上面表格里的东西一个字符都不用动，默认值就是答案。下面两个场景只针对特殊环境，如果你不需要跨机器，直接跳到"能拿它做什么"一章。
场景二：Docker、WSL 或远程主机
核心原则一句话：Blender 必须监听在 MCP 进程够得着的地方。Blender 装在容器里、或服务端跑在另一台机器上时，给配置补一段env：
{ "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"], "env": { "BLENDER_HOST": "host.docker.internal", "BLENDER_PORT": "9876" } } } }这段配置的意思是：服务端不再拨 localhost，改拨容器网络里那个专用地址。WSL2 连 Windows 侧的 Blender 时，先试BLENDER_HOST=127.0.0.1，不通再换成 Windows 主机 IP。另外服务端连网时会自动依次尝试几个常见别名（localhost会顺带试127.0.0.1，host.docker.internal会顺带试172.17.0.1），所以能交给代码判断的，就别手动写死 IP。
视口截图是以 base64 内嵌返回的，不依赖共享临时目录，远程场景照样能用。
场景三：Python 版本打架的机器
机器上装了 conda、pyenv，或者 Apple Silicon 上uvx拉错架构的包去编译，就把 Python 钉死：
{ "mcpServers": { "blender": { "command": "uvx", "args": ["--python", "3.11", "blender-mcp"], "env": { "UV_PYTHON_PREFERENCE": "only-managed" } } } }这段配置的意思是：让uvx只用它自己管理的干净 Python 3.11，别碰系统里那些来路不明的解释器。Apple Silicon 上把3.11换成3.11-aarch64更稳。完全不想用 uv 的话，pipx install blender-mcp装出来效果等价。
能拿它做什么：从一句话建场景，到任意代码与外部资源库
接通之后，按下面三个层次由浅入深用一遍，你对这套工具会有实感。
层次一：一句话建场景，再让 AI 自己核对
建完别急着说"看起来不错"，追加一句："用截图确认一下场景状态"。这会触发get_viewport_screenshot工具，AI 拿着视口图片"亲眼"复查自己的活——火把悬空、门歪了、物体没对齐，它自己找出来再改。这一招把交互从"盲改"变成了"操作 → 截图验证 → 修正"的闭环，效果稳定得多。
层次二：跑任意 Python，把材质控制到最细
execute_blender_code工具能在 Blender 里执行任意 Python。你说"把这个立方体变成金色金属"，AI 背后跑的就是这段逻辑：
import bpy mat = bpy.data.materials.new(name="GoldMaterial") # 新建材质 mat.use_nodes = True nodes = mat.node_tree.nodes for node in nodes: nodes.remove(node) # 清掉默认节点树 output = nodes.new(type='ShaderNodeOutputMaterial') # 输出节点 principled = nodes.new(type='ShaderNodeBsdfPrincipled') # PBR 节点 links = mat.node_tree.links links.new(principled.outputs[0], output.inputs[0]) principled.inputs['Base Color'].default_value = (0.9, 0.7, 0.1, 1) # 金色 principled.inputs['Metallic'].default_value = 1.0 principled.inputs['Roughness'].default_value = 0.2 if bpy.context.active_object.data.materials: bpy.context.active_object.data.materials[0] = mat else: bpy.context.active_object.data.materials.append(mat) # 挂到当前选中物体⚠️ 这条工具等于把 Blender 的控制权整个交给模型，操作前先保存文件，这是铁律。
层次三：接上内置资源管道，用外部资产组装场景
插件端内建了几条能"进货"的管道，在侧边栏 BlenderMCP 面板里勾选对应功能，然后直接在对话里指挥：
- Poly Haven：无需密钥，说一句"用 Poly Haven 的 HDRI、岩石和植被做个海滩氛围"，AI 会自动搜索下载，HDR 直接设为世界环境
- Sketchfab：填好 API Key 后，"在 Sketchfab 上搜一把中世纪椅子并导入"——先取缩略图预览、确认后下载，还能按目标尺寸归一化（椅子 1 米、桌子 0.75 米）
- Hyper3D Rodin / Hunyuan3D：生成式建模，描述一下"这个库里找不到的定制物件"，它生成自带材质的模型再导进场景
选择顺序记一句就行：具体现成的物件先查 Sketchfab，通用环境资产先查 Poly Haven，找不到的定制需求再上生成式模型，环境光永远直接拿 Poly Haven 的 HDRI。Sketchfab、Hyper3D 这些密钥存在编辑 > 偏好设置 > 插件 > Blender MCP里（对应环境变量BLENDERMCP_SKETCHFAB_API_KEY、BLENDERMCP_HYPER3D_API_KEY等），填一次就持久保留。
按症状对号入座：连接不上的 5 个高频问题
现象：报spawn uvx ENOENT，客户端根本没把服务拉起来
原因：图形界面客户端不继承终端的 PATH，找不到uvx。解法：查全路径，把结果直接填进配置的command：
which uvx # macOS / Linux where uvx # WindowsWindows 也可以让cmd先代跑一层：
{ "mcpServers": { "blender": { "command": "cmd", "args": ["/c", "uvx", "blender-mcp"] } } }这段配置的意思是：先调起cmd外壳，再由它执行uvx，绕开 GUI 程序找不到命令的问题。改完配置，完全退出客户端再重开。
现象：各端都启动了，但 AI 说连不上 Blender，或一直超时
原因：插件端的 socket 没在监听，或两边的主机 / 端口没对上。逐条过：① 回 Blender 侧边栏，确认面板显示Running on port 9876；② 核对插件面板端口与BLENDER_PORT一致；③ 确认防火墙放行 9876。⚠️ 最容易漏的一条：Blender 必须跑 GUI 模式——用blender -b后台模式启动时，插件会拒绝开服务，输出里会打出一行cannot start server in background mode。
现象：第一条指令没反应
原因：插件首次建立 socket 连接，第一发经常丢。解法：把同样的指令重发一次，一般就通了。
现象：命令卡很久、180 秒超时，或者两条命令的响应串了线
原因：要么单次任务太大，socket 一直等到超时（服务端与插件都设了 180 秒）；要么是同时挂着两个 MCP 客户端（比如 Cursor 和 Claude 各拉了一份服务）在抢同一个端口，就像两个人占了一条线。解法：大任务拆成几步小指令，一步步喂；同一时间只保留一个客户端在跑。
现象：uvx 报编译错误，或者怀疑版本还是旧的
原因：机器上的 Python 与依赖冲突，或本地缓存没刷新。解法：钉住 Python 版本（见场景三），然后清缓存强制刷新：
uv cache clean blender-mcp && uvx --refresh blender-mcp # 清掉 blender-mcp 的缓存后重新拉取以上都试过还不通，就祭出三板斧：重启 Blender 插件、重启 MCP 客户端、把配置里的 blender 服务删掉重新添加一次，基本能覆盖绝大多数"幽灵问题"。
跑通自检清单与源码入口
收个尾，照着这份清单打勾：
- ☐ uv 装好，
uvx --version有输出 - ☐ 客户端配置写完，客户端已完全重启
- ☐
addon.py装好并启用，侧边栏面板显示Running on port 9876 - ☐ 第一条指令跑通，并配合截图验证了一次
- ☐ 试过至少一个外部资源（Poly Haven 或 Sketchfab）
- ☐ 服务端与插件两端的端口核对一致
想读代码弄清机制，两个入口：src/blender_mcp/server.py 里的BlenderConnection类，那把保证"两条命令不会在同一条 socket 上互相串线"的锁就在里面，主机别名重试逻辑也在同一个文件里；addon.py 则是插件端注册侧边栏面板、端口监听循环与后台模式检查的地方。遥测开关的逻辑单独放在 src/blender_mcp/config.py，想彻底关掉统计时可以去那里确认BLENDER_MCP_DISABLE_TELEMETRY的判定过程。
【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
