企业官网建设流程全解析

BlenderMCP 完整实战：AI 控制 Blender 3D 配置与连接避坑

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

如果你正在找用自然语言操控 Blender 3D 的 MCP 配置方法，这篇文章覆盖从装 uv、写客户端配置到排查连接失败的全过程，并附参数速查表和高频坑清单。适合刚接触 BlenderMCP 的新手。

BlenderMCP 由什么构成

BlenderMCP 是一个让任意大模型（Claude、Cursor 内置模型等）通过 MCP 协议（一套 AI 调用外部工具的标准接口）驱动 Blender 的开源插件：建物体、换材质、截视口、跑 Python，全都能用一句话指挥。

系统分两半：跑在电脑上的 MCP 服务端，负责把 AI 的意图翻译成指令；住在 Blender 里的addon.py插件，负责真正动手。两者之间靠一条 TCP 连接对话，默认端口 9876——端口不一致，两边就互相听不见。

最小跑通三步

第 1 步：安装 uv

服务端是 Python 写的，uv 是它的启动器兼包管理器。按系统选一条执行，装完重启终端：

# Linux curl -LsSf https://astral.sh/uv/install.sh | sh # macOS brew install uv

Windows 在 PowerShell 执行powershell -c "irm https://astral.sh/uv/install.ps1 | iex"，再把%USERPROFILE%\.local\bin加进 PATH。💡 验证标准：新终端里uvx --version能打印版本号。⚠️ 别用pip install uv凑合，它经常不生成uvx命令。

第 2 步：把 AI 客户端指向 BlenderMCP

以 Claude 桌面版为例，打开设置 > 开发者 > 编辑配置，往claude_desktop_config.json里贴这段：

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

意思是：客户端启动时自动用uvx拉起 blender-mcp 服务，你不需要手动跑。💡 验证标准：完全退出并重启 Claude，对话里出现锤子图标，说明服务已被识别。

第 3 步：装插件并点 Connect

1. 拿仓库根目录的 addon.py（整个插件就这一个文件）
2. Blender 里编辑 > 偏好设置 > 插件，点"安装..."选中它
3. 勾选启用"Interface: Blender MCP"
4. 3D 视图按N唤出侧边栏，切到 BlenderMCP 标签，点Connect to Claude

💡 验证标准：侧边栏显示"运行中"。这时在对话里发"创建一个低多边形场景"，视口会自己动起来。

可调参数速查与场景变体

⚠️ Blender 插件和服务端各有一份端口，两边数字必须一致，否则就是一个人敲错门。

本地标准接入：上面第 2 步的 JSON 即可直接用。机器上有 conda/pyenv 容易打架时，钉死一个干净的 Python：

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

Cursor（Windows）：图形界面程序不继承终端 PATH，先调起cmd再执行uvx：

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

Docker / WSL / 远程主机：原则是 Blender 必须监听在 MCP 进程够得着的地方，配置里加env：

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

WSL2 连 Windows 版 Blender 优先试127.0.0.1，不行再换 Windows 主机 IP。截图走 base64 返回，不依赖共享目录，远程场景没问题。

纯 CLI 调用：不想维护配置文件，一行加好：

claude mcp add blender uvx blender-mcp

实战两例：建场景与改材质

入门｜一句话建场景：先确认侧边栏"运行中"，然后发"创建一个低多边形地牢，里面有火把、石柱和一扇铁门"。完成后追加一句"截个视口图确认一下"——AI 会触发视口截图，自己检查哪里歪了，你再指哪修哪。这套"指令 → 截图验证 → 修正"的闭环比盲改可靠得多。

从入门到进阶的跨度就在这：自然语言只到"意图"为止，而进阶操作是看 AI 把意图翻译成在 Blender 里执行的 Python，并直接掌控它。

进阶｜精确控制材质：你说"把选中立方体变成金色金属"，AI 背后走execute_blender_code工具，跑的就是类似这段逻辑：

import bpy obj = bpy.context.active_object mat = bpy.data.materials.new("Gold") mat.use_nodes = True nodes, links = mat.node_tree.nodes, mat.node_tree.links nodes.clear() out = nodes.new("ShaderNodeOutputMaterial") bsdf = nodes.new("ShaderNodeBsdfPrincipled") links.new(bsdf.outputs[0], out.inputs[0]) bsdf.inputs["Base Color"].default_value = (0.9, 0.7, 0.1, 1) bsdf.inputs["Metallic"].default_value = 1.0 bsdf.inputs["Roughness"].default_value = 0.2 obj.data.materials.append(mat)

这段代码新建一个 Principled 材质，接好输出节点，把颜色、金属度、粗糙度调到金色质感，再挂到当前物体的网格上。

⚠️execute_blender_code能跑任意 Python，等于把 Blender 整个交给 AI——动手前先保存文件，这是铁律。

高频坑 TOP 5（按踩坑频率排）

坑 1：报spawn uvx ENOENT，客户端起不来根因：图形界面客户端不继承终端 PATH，找不到uvx。 解法：①which uvx（Windows 用where uvx）查全路径；② 把返回的完整路径填进配置的"command"，或 Windows 走cmd /c写法；③ 完全退出客户端重开。

坑 2：服务端正常，AI 却说连不上 Blender根因：插件端 socket 没在听，或两侧主机/端口对不上。 解法：① 回侧边栏确认"运行中"；② 核对插件面板端口与BLENDER_PORT一致；③ 确认防火墙放行 9876；④blender -b后台模式下命令永远执行不了，必须用带界面的 Blender。

坑 3：指令发出去卡很久，超时或流式响应错乱根因：单次 socket 超时上限默认 180 秒，大任务一次做不完；或多个客户端同时挂服务抢同一端口。 解法：把大任务拆成几条小指令分步喂；同一时间只保留一个 MCP 客户端在跑。

坑 4：uvx 各种编译报错，Python 版本打架根因：conda/pyenv 里的 Python 与依赖不兼容，Apple Silicon 上还可能被拉去编 x86_64 的包。 解法：配置写"args": ["--python", "3.11", "blender-mcp"]加"env": { "UV_PYTHON_PREFERENCE": "only-managed" }；M 系 Mac 可试"args": ["--python", "3.11-aarch64", "blender-mcp"]。

坑 5：以上都试过还是不通终极操作三板斧：重启 Blender 插件端 → 完全重启 MCP 客户端 → 把配置里的 blender 服务删掉重新添加一遍。多数"幽灵问题"到此为止。

往深走的方向与行动清单

• 想看连接机制：server.py 里的BlenderConnection，能看清主机/端口如何被解析、超时怎么兜底

• 想看面板与监听怎么注册：addon.py

• 想关掉遥测并理解它上报什么：telemetry.py

• 关心代码执行的安全边界：SECURITY.md

• ☐uvx --version有输出

• ☐ 客户端配置写好并完全重启了客户端

• ☐addon.py装好，侧边栏显示"运行中"

• ☐ 第一条指令发出，配合截图让 AI 自查过一轮

• ☐ 试跑一个外部资源库（Poly Haven 或 Sketchfab）

• ☐ 把坑位清单存下来，下次对号入座

卡住的话直接来问：贴上报错原文、客户端类型、系统版本，比"好像连不上"好定位得多。

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