企业官网建设流程全解析

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

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

BlenderMCP 把 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 的版本确认

跑通前确认三样东西：

按系统安装 uv：

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

Windows 用 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 插件

1. 拿到 addon.py（仓库根目录就有；也可git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp后直接引用本地文件）
2. Blender 里打开 编辑 > 偏好设置 > 插件 > 安装...，选择它
3. 勾选 "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_TELEMETRY=true，或在 Blender 偏好设置的插件选项里取消遥测勾选。

另一个容易忽略的点：插件侧也支持改端口（侧边栏 BlenderMCP 面板里有端口设置）。只要它不是 9876，MCP 侧的BLENDER_PORT必须跟着对齐，两边不一致就是连不上。

客户端配置变体：Cursor、VS Code 与 Claude Code

除 Claude Desktop 外，几个常见入口的写法（本质都是 stdio 拉起同一个进程）：

• Cursor / VS Code（macOS、Linux）：与上文 Claude 的 JSON 相同。
• Cursor（Windows）：用cmd /c uvx blender-mcp的转发写法。
• Claude Code 命令行：claude mcp add blender uvx blender-mcp。

⚠️ 同一时间只在一个客户端里启用 blender-mcp。两个客户端会各拉一条连接去抢同一条 9876 管道，症状是时好时坏的超时，排查起来很耗时间。

故障速查：4 类连接问题的定位顺序

① spawn uvx ENOENT / 报找不到命令GUI 客户端不继承终端 PATH。终端跑which uvx（macOS / Linux）或where uvx（Windows），把拿到的完整路径填进"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