从 uvx 命令行到端口 9876：BlenderMCP 接入 Claude 的 3 步配置与 4 类连接故障

从 uvx 命令行到端口 9876BlenderMCP 接入 Claude 的 3 步配置与 4 类连接故障【免费下载链接】blender-mcpCommunity plugin to control Blender 3D with any LLM of your choice项目地址: https://gitcode.com/GitHub_Trending/bl/blender-mcpBlenderMCP 把 Blender 接到任意 LLM 客户端你在 Claude 里说一句建个低多边形地牢它就真能在场景里建模、调材质、下 HDRI。这篇文章带你装好插件、写好 MCP 配置、调通 9876 端口并覆盖 4 类最常见的连接故障。先花 30 秒看懂链路一句话AI 不直接控制 Blender中间隔着一条 TCP 管道。你的 AI 客户端 ←MCP→ blender-mcp 服务器 ←TCP:9876→ Blender 插件插件侧addon.py在 Blender 内部起一个套接字服务收到 JSON 指令后在场景里执行。服务器侧src/blender_mcp/server.py实现 MCP 协议把工具调用翻译成对插件的指令。排错前先分清断点在哪一段AI 客户端里看不到 Blender 工具多半是 MCP 配置没生效工具点了才报错多半是插件没点 Connect或地址、端口对不上。环境自检Blender、Python 与 uv 的版本确认跑通前确认三样东西依赖最低要求说明Blender3.04.x / 5.x 更稳必须带 GUIblender -b后台模式跑不了Python3.10uvx 会自行管理运行时uv最新版提供uvx命令按系统安装 uv# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | shWindows 用 PowerShell 执行powershell -c irm https://astral.sh/uv/install.ps1 | iex再把%USERPROFILE%\.local\bin加进 PATH重启终端。 别用pip install uv。它经常装不出uvx可执行文件这是后文 spawn uvx ENOENT 的头号来源。装完立刻验证uvx --version最小可跑通路径装插件 → 写配置 → 点 Connect第 1 步安装 Blender 插件拿到 addon.py仓库根目录就有也可git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp后直接引用本地文件Blender 里打开 编辑 偏好设置 插件 安装...选择它勾选 Interface: Blender MCP第 2 步在客户端登记 MCP 服务器Claude Desktop 打开 设置 开发者 Edit Config写入claude_desktop_config.json{ mcpServers: { blender: { command: uvx, args: [blender-mcp] } } }Windows 下 GUI 客户端不继承终端 PATH常找不到uvx改成经 cmd 转发command: cmd, args: [/c, uvx, blender-mcp]保存后把客户端完全退出再重开热加载不生效。第 3 步在 Blender 侧发起连接在 3D 视图按 N 打开侧边栏切到 BlenderMCP 选项卡点 Connect to Claude。想下载 Poly Haven 的 HDRI、纹理和模型先把对应开关勾上再连。连上后回到 AI 客户端工具列表出现 Blender 相关工具Claude 里显示为一个锤子图标直接下指令即可。参数配置深挖BLENDER_HOST 与 BLENDER_PORT本地开发用默认值就行主机localhost、端口9876什么都不用配。src/blender_mcp/server.py 会读这两个环境变量未设置时落到默认值。需要改的只有两种场景1. Blender 跑在别的机器或容器里。MCP 进程必须能通过网络够到 Blender在客户端配置的env里指定env: { BLENDER_HOST: host.docker.internal, BLENDER_PORT: 9876 }WSL2 连 Windows 宿主机的 Blender 时BLENDER_HOST填127.0.0.1或宿主机局域网 IP。服务器代码里对host.docker.internal还内置了172.17.0.1兜底就是为容器场景准备的。2. 不想上传匿名使用统计。加环境变量BLENDER_MCP_DISABLE_TELEMETRYtrue或在 Blender 偏好设置的插件选项里取消遥测勾选。另一个容易忽略的点插件侧也支持改端口侧边栏 BlenderMCP 面板里有端口设置。只要它不是 9876MCP 侧的BLENDER_PORT必须跟着对齐两边不一致就是连不上。客户端配置变体Cursor、VS Code 与 Claude Code除 Claude Desktop 外几个常见入口的写法本质都是 stdio 拉起同一个进程Cursor / VS CodemacOS、Linux与上文 Claude 的 JSON 相同。CursorWindows用cmd /c uvx blender-mcp的转发写法。Claude Code 命令行claude mcp add blender uvx blender-mcp。⚠️ 同一时间只在一个客户端里启用 blender-mcp。两个客户端会各拉一条连接去抢同一条 9876 管道症状是时好时坏的超时排查起来很耗时间。故障速查4 类连接问题的定位顺序① spawn uvx ENOENT / 报找不到命令GUI 客户端不继承终端 PATH。终端跑which uvxmacOS / Linux或where uvxWindows把拿到的完整路径填进command字段改完重启客户端。② 连不上 Blender / 工具调用报错先确认 Blender 侧已处于连接状态再核对 MCP 侧BLENDER_HOST指向同一台机器。别在终端里手动uvx blender-mcp占着进程——服务器应由客户端拉起另外第一条指令偶尔会失败重试一次通常就好。③ Apple Silicon 上报 cryptography 构建失败说明 uvx 按错了架构编译依赖在 args 里强制 arm64 解释器args: [--python, 3.11-aarch64, blender-mcp]④ 复杂指令超时一条提示词干太多事建场景 布光 下载材质容易卡住。拆成顺序短句逐步执行还超时就uv cache clean blender-mcp后uvx --refresh blender-mcp清缓存重拉。排完四类仍有问题把 Blender 插件和客户端都重启一次再不行就在客户端删掉 blender 服务重新添加。安全提醒execute_blender_code 会执行任意 Python工具集里的execute_blender_code会直接在你的 Blender 中运行任意代码改坏场景不可逆。用它之前先保存 .blend 文件回滚才有底。下一步用 Poly Haven 的 HDRI 加岩石、植被搭一个海滩场景验证资产下载链路对现有模型下改成红色金属材质这类指令熟悉节点级材质控制试一次 Hyper3D 文生 3D如 garden gnome体验完整资产生成流程延伸阅读README.md、addon.py、src/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），仅供参考