BlenderMCP 参数配置全攻略从零跑通 uvx 命令行连接 Blender【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp我明明照着教程装好了为什么 AI 还是说连接不上 Blender——这是每个第一次接触 BlenderMCP 参数配置的人都会撞上的墙。网上教程东一句西一句环境变量、端口号、插件顺序一步错步步错。别慌这篇攻略就是为照着做就能成而写的从安装到命令行从环境变量到报错排查一次性讲透。读完你将掌握✅ 5 分钟搭好最小运行环境让 AI 第一次看见你的 Blender 场景✅ 搞懂BLENDER_HOST和BLENDER_PORT这两个核心环境变量到底该怎么设✅ 在 Claude Desktop、Cursor、VS Code 里正确接入 BlenderMCP 服务器✅ 三类高频报错连接超时、uvx 找不到、多客户端冲突的排查套路✅ 进阶玩法Poly Haven 资产、AI 生成模型、视口截图等实用功能一、先弄明白它凭什么能指挥BlenderBlenderMCP 是一套社区开源的桥接方案核心思路很朴素通过模型上下文协议MCP把大语言模型和 Blender 3D 连起来让你用自然语言直接建模、打光、改材质。整套系统只有两个零件组件位置职责Blender 插件addon.py在 Blender 内部启动一个基于套接字的服务端负责真正执行命令MCP 服务器src/blender_mcp/server.py实现 MCP 协议负责和 AI 客户端对话再把指令转发给 Blender两者之间走的是TCP 协议默认地址是localhost:9876。记住这个端口号后面所有配置都围绕它展开AI 客户端 --MCP-- MCP 服务器(src/blender_mcp/server.py) --TCP:9876-- Blender 插件(addon.py)好消息是只要这两个零件都醒着剩下的就是配置问题而配置就那几个变量。二、最快上手5 分钟跑通最小配置先别管那些花哨功能按下面四步走最快路径只要几分钟。第 1 步装好 uv 包管理器BlenderMCP 官方推荐用uv来运行因为它能自动帮你拉好 Python 环境和依赖省去一堆麻烦。根据你的系统选一条命令# macOS 用户 brew install uv # Windows 用户PowerShell 中执行 powershell -c irm https://astral.sh/uv/install.ps1 | iex # Linux 用户 curl -LsSf https://astral.sh/uv/install.sh | sh⚠️ 千万别用pip install uv装出来的环境可能没有uvx命令后面会卡在启动那一步。第 2 步把插件装进 Blender去仓库下载addon.py文件clone 仓库的命令在文末然后打开 Blender进入编辑 偏好设置 插件点击右上角安装...选中你下载的addon.py在插件列表里找到并勾选Interface: Blender MCP第 3 步写入 Claude Desktop 配置打开 Claude 的配置文件设置 开发者 编辑配置找到claude_desktop_config.json把下面这段标准答案填进去{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }保存后完全退出并重启 Claude让配置生效。第 4 步在 Blender 里点击连接在 3D 视图里按N键唤出侧边栏切换到BlenderMCP选项卡点击Connect to Claude连接成功后Claude 对话窗口里会出现一个锤子图标代表 Blender 的工具已经就绪。这时你直接说在场景里加一个金属质感的球体就能看到 Blender 里的物体真的动起来了。三、核心参数精讲这两个环境变量这样设才对很多教程会把环境变量一笔带过但BLENDER_HOST和BLENDER_PORT恰恰是连接成败的分水岭。先看官方默认值环境变量默认值作用设置示例BLENDER_HOSTlocalhostBlender 套接字服务端的主机地址export BLENDER_HOSThost.docker.internalBLENDER_PORT9876套接字服务端监听的端口号export BLENDER_PORT9876设置方式有两种任选其一方式一终端里 export临时生效export BLENDER_HOSTlocalhost export BLENDER_PORT9876方式二写进客户端配置文件推荐重启不丢{ mcpServers: { blender: { command: uvx, args: [blender-mcp], env: { BLENDER_HOST: host.docker.internal, BLENDER_PORT: 9876 } } } }什么时候需要改BLENDER_HOST在Docker / WSL / 远程主机里跑 MCP 服务器时Blender 可能跑在宿主机上这时要写成host.docker.internalWSL2 连接 Windows 版 Blender 时试试127.0.0.1或你 Windows 主机的实际 IP⚠️ 注意BLENDER_PORT改动后插件侧和 MCP 服务器侧必须一致端口不一致会出现能连上但命令全部超时的诡异现象。四、把 uvx blender-mcp 命令行用明白uvx blender-mcp是 BlenderMCP 的启动入口它的职责只有一个拉起 MCP 服务器。基本用法如下uvx blender-mcp但这里有个新手最容易踩的坑不要自己在终端里手动运行这条命令。正常情况下MCP 服务器是由 AI 客户端Claude、Cursor 等在启动时自动拉起的你手动跑一个反而可能抢占端口、造成混乱。那命令行到底什么时候用两个场景场景一验证环境是否正常# 确认 uvx 是否可用以及它的完整路径 which uvx # macOS / Linux where uvx # Windows如果which uvx没输出说明 uv 没装好或没进 PATH回到第二节重装。场景二配合其他环境变量做精细化控制# 指定主机与端口后启动适合调试远程连接 export BLENDER_HOSThost.docker.internal export BLENDER_PORT9876 uvx blender-mcp还有一个值得知道的开关——关闭匿名遥测。BlenderMCP 默认会上报工具使用情况不含敏感内容如果你介意隐私可以这样关BLENDER_MCP_DISABLE_TELEMETRYtrue uvx blender-mcp或者在客户端配置里加env: { BLENDER_MCP_DISABLE_TELEMETRY: true }效果相同。五、主流编辑器对接实操不同客户端对启动命令的口味不一样下面三份配置直接抄。Claude Desktop{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }如果机器上装了 conda / pyenv 导致 Python 版本冲突可以锁定 3.11{ mcpServers: { blender: { command: uvx, args: [--python, 3.11, blender-mcp], env: { UV_PYTHON_PREFERENCE: only-managed } } } }CursorWindows 用户注意写法Windows 下 GUI 客户端不会继承终端 PATH需要包一层cmd{ mcpServers: { blender: { command: cmd, args: [/c, uvx, blender-mcp] } } }macOS / Linux 用户则直接写uvx即可。VS Code{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }⚠️多客户端冲突警告同一时间只运行一个 MCP 服务器Cursor 和 Claude Desktop 同时开启会争抢 9876 端口导致两边都连不上。用完一个再开另一个。六、高频问题排查清单连接出问题先别慌对照下面的现象 → 原因 → 解决三步走绝大多数都能自己搞定。问题 1报错spawn uvx ENOENT现象客户端提示找不到uvx命令原因GUI 客户端没有继承终端里的 PATH找不到可执行文件解决终端里执行which uvxWindows 用where uvx拿到完整路径把它填到配置的command字段例如/Users/you/.local/bin/uvx改完彻底重启客户端问题 2一直连接超时现象AI 回复连接失败或长时间无响应原因Blender 插件没启动、防火墙挡了 9876 端口或BLENDER_HOST指向了错误地址解决先确认插件侧边栏已显示连接状态再检查防火墙放行 9876最后核对环境变量是否与插件一致。另有一个小技巧第一条指令失败是常见现象重试一次往往就好了问题 3复杂的指令总是做到一半超时现象像创建整个地牢场景这种大指令经常失败原因单条命令工作量太大超出了套接字的响应时限解决把大需求拆成几条小指令依次执行比如先创建地面和墙壁再添加一条龙最后加上金币罐问题 4苹果芯片M1/M2/M3/M4架构报错现象uvx在 arm64 的 Mac 上尝试构建 x86_64 的包报 cryptography 相关的错解决在args里强制指定 arm64 的 Pythonargs: [--python, 3.11-aarch64, blender-mcp]七、进阶玩法与下一步行动跑通基础连接后BlenderMCP 的想象力才真正打开。目前它内置了不少外挂级别的能力能力说明在哪开启Poly Haven 资产直接下载 HDRI、纹理和现成模型插件侧边栏勾选Hyper3D Rodin用文字或参考图生成 3D 模型插件偏好设置里填 API KeyHunyuan3D腾讯的开源 3D 生成模型插件偏好设置里填凭证Sketchfab搜索并导入海量 3D 模型插件偏好设置里填 API Key视口截图让 AI 看到当前渲染画面理解场景直接说截图看看当前场景API Key 统一存在编辑 偏好设置 插件 Blender MCP里对应的环境变量名分别是BLENDERMCP_SKETCHFAB_API_KEY、BLENDERMCP_HYPER3D_API_KEY等重启后依然保留。上手后可以试试这些指令找感觉创建一个低多边形地牢一条龙守护着一罐金子用 Poly Haven 的 HDRI、岩石和植被搭一个海滩场景把当前选中的车改成红色金属材质给场景布置影棚灯光和等距相机⚠️安全提醒BlenderMCP 支持在 Blender 内执行任意 Python 代码execute_blender_code功能强大的同时意味着风险。使用前记得先保存工程文件也尽量别把敏感对话喂给它。如果对内部实现好奇建议顺着这几份源码读下去MCP 服务器的核心逻辑在 src/blender_mcp/server.py连接配置与遥测开关在 src/blender_mcp/config.py完整功能列表见项目根目录的 README.md。下一步行动清单按第二节跑通最小配置确保锤子图标出现做一次改环境变量 → 重启客户端 → 验证连接的完整实验把BLENDER_HOST的三种写法localhost / host.docker.internal / 远程 IP各试一遍尝试第一条 Poly Haven 资产下载指令读完config.py顺手把遥测开关按你的偏好设置好需要 clone 完整仓库自己折腾的话执行git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp从连接不上到说一句话就长出个场景你差的只是这一套配置。现在就去试试吧。【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
