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.xPython 3.10 及以上。第 1 步装好 uvuv是 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_HOSTlocalhost服务端拨号去找插件的主机地址Blender 在容器 / 远程机器上时BLENDER_PORT9876服务端拨的端口号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_HOST127.0.0.1不通再换成 Windows 主机 IP。另外服务端连网时会自动依次尝试几个常见别名localhost会顺带试127.0.0.1host.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(nameGoldMaterial) # 新建材质 mat.use_nodes True nodes mat.node_tree.nodes for node in nodes: nodes.remove(node) # 清掉默认节点树 output nodes.new(typeShaderNodeOutputMaterial) # 输出节点 principled nodes.new(typeShaderNodeBsdfPrincipled) # 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。解法查全路径把结果直接填进配置的commandwhich 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），仅供参考