企业官网建设流程全解析

BlenderMCP安装与配置指南：从跑通到排障

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

当你在 Blender 里想用一句话直接造出 3D 场景时，BlenderMCP 就能让 AI 助手实时创建、修改 Blender 中的对象。本文带你完成 uv 安装、客户端配置和插件接入三个环节，覆盖：最短路径跑通、环境变量逐项说明、端口占用与多客户端冲突的排查顺序。

先跑通：最短路径接入

按顺序执行 6 步，先看到"连上了"的信号，再回头补细节。

1. 安装 uv（Astral 出品的 Python 包管理器，uvx是它的一次性运行命令）：

   # 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"

   安装后在终端确认uvx --version有输出。Windows 用户需把%USERPROFILE%\.local\bin加入 PATH，然后重启客户端。

2. 获取插件文件。如果仓库已克隆（git clone https://gitcode.com/GitHub_Trending/bl/blender-mcp），直接使用根目录的 addon.py；否则从项目仓库下载该文件。

3. Blender 中依次点击 编辑 > 偏好设置 > 插件 > 安装...，选择addon.py。

4. 启用Interface: Blender MCP插件，关闭偏好设置窗口。

5. 在 Claude Desktop 中打开 设置 > 开发者 > 编辑配置，把以下内容写入claude_desktop_config.json，再完全退出并重启 Claude Desktop：

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

6. 回到 Blender，在 3D 视图按N打开侧边栏，切到BlenderMCP选项卡，点击Connect to Claude。

成功信号：侧边栏状态变为已连接，同时 Claude 对话界面出现锤子图标，表示 Blender 工具已激活。此时发一句"Create a low poly dungeon with a dragon guarding gold"，场景里会开始出物体。

⚠️ 不要手动在终端运行uvx blender-mcp——MCP 服务器由客户端自动拉起，手动多开会导致连接状态混乱。

💡 不要用pip install uv安装 uv，它可能不生成uvx命令。

它是怎么工作的：三个组件，一条 TCP 线

整条链路只有三个组件，各管一段：

• AI 客户端（Claude Desktop / Cursor / VS Code）：你输入提示词的地方，它负责按配置自动启动uvx blender-mcp。
• MCP 服务器（src/blender_mcp/server.py）：实现模型上下文协议（MCP，一种让 LLM 调用外部工具的开放协议），把 AI 的工具调用翻译成套接字命令，并读取BLENDER_HOST/BLENDER_PORT决定连向哪里。
• Blender 插件（addon.py）：在 Blender 进程内开一个 TCP 套接字服务器（默认 9876 端口），收到命令后执行（建对象、改材质、跑 Python），再把结果以 JSON 返回。

调用方向是单向链：客户端 <--MCP/stdio--> 服务器 <--TCP:9876--> 插件。一次调用的报文长这样：

{ "type": "create_object", "params": { "type": "SPHERE", "name": "Ball" } } { "status": "success", "result": { "name": "Ball", "location": [0, 0, 0] } }

插件侧的连接入口在侧边栏，截图如下：

配置逐项说明：环境变量与配置文件

所有连接参数都通过环境变量注入，MCP 服务器启动时读取。改的位置只有两处：终端（手动运行时）或客户端配置里的env字段（客户端托管时，推荐）。

手动运行时这样注入：

export BLENDER_HOST='localhost' export BLENDER_PORT=9876 uvx blender-mcp

客户端托管时在配置里加env字段：

"env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }

Claude Desktop

用「先跑通」一节的配置即可。如果你的机器上 conda / pyenv 的 Python 与 uv 冲突，把args改成["--python", "3.11", "blender-mcp"]，并加"env": { "UV_PYTHON_PREFERENCE": "only-managed" }，让 uv 只用自己管理的解释器。

Cursor

macOS / Linux 与 Claude Desktop 完全相同。Windows 上uvx不是原生可执行文件，需要套一层cmd：

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

VS Code 与其他客户端

VS Code 的 MCP 配置结构与上面一致（command+args）。Claude Code CLI 可以一条命令注册：

claude mcp add blender uvx blender-mcp

Docker / WSL / 远程主机

Blender 和 MCP 服务器不在同一台机器时，把BLENDER_HOST指向 Blender 一侧可达的地址。Docker 里连宿主机 Blender 用host.docker.internal（服务器还会自动尝试172.17.0.1）；WSL2 里连 Windows 的 Blender，先试127.0.0.1，不通再换成 Windows 宿主机的 IP。

验证与排障：连接不上时的排查顺序

从最常见到最少见，按顺序逐条核对，每条先认现象、再给动作。

1. 第一条提示词失败、后续正常：插件服务器刚启动时首条命令经常丢失。现象是首次调用报错但场景没变化；动作是原样重发一次，并确认侧边栏显示已连接。
2. 客户端报spawn uvx ENOENT：GUI 客户端不继承终端 PATH，找不到uvx。动作是终端执行which uvx（macOS/Linux）或where uvx（Windows），把输出的完整路径填进配置的"command"，改完完全重启客户端。
3. 端口 9876 被占用：现象是插件点击 Connect 失败，或 MCP 服务器报Could not connect to Blender (tried ...)。同一时间只能有一个进程监听 9876。动作是确认没有残留的旧 Blender 进程或手动起的uvx实例；确需并存时，把双方的BLENDER_PORT同步改成别的值。
4. 多客户端冲突：同时开 Cursor 和 Claude Desktop 各跑一个 MCP 服务器时，两个服务器抢同一条到插件的 TCP 连接，表现为指令时灵时不灵、状态反复断开。动作是只保留一个客户端在跑，另一个从配置里移除（README 明确建议：一次只跑一个）。
5. 跨环境连不通：现象是本地localhost明明没问题，容器/WSL 里却超时。动作是核对「配置逐项说明」最后一节的BLENDER_HOST取值，并用报错里tried ...列出的候选确认服务器实际尝试过哪些地址。
6. 复杂场景请求超时：现象是让 AI 一次搭建完整场景时中途超时。动作是把请求拆成多轮小步骤（先建结构、再加材质、最后布光）。
7. Python 版本冲突 / cryptography 报错：常见于 Apple Silicon 上误用 x86_64 解释器。动作是在args里加--python参数（如["--python", "3.11-aarch64", "blender-mcp"]），再清缓存：uv cache clean blender-mcp && uvx --refresh blender-mcp。
8. 以上都不对症：动作是重启 MCP 客户端、重启 Blender 插件服务器，然后只发一条最简单的指令（如"新建一个球体"）复测。

进阶用法：可直接复用的示例

• 验证链路是否完整（场景：刚装好，想确认 AI 真能操控 Blender）：

  Create a low poly dungeon with a dragon guarding gold

• 写实氛围搭建（场景：需要真实光照与材质，先在侧边栏勾选 Poly Haven 复选框，再发）：

  Beach scene with Poly Haven HDRIs, rocks, and vegetation

• 局部改材质（场景：已有模型，只想改外观，不用重建）：

  Make this car red and metallic

不想上报匿名统计时，在配置的env里加"BLENDER_MCP_DISABLE_TELEMETRY": "true"，或手动运行时：

BLENDER_MCP_DISABLE_TELEMETRY=true uvx blender-mcp

注意execute_blender_code工具会在 Blender 内执行任意 Python，用它改动场景前先保存工程。

完整功能列表（Poly Haven、Sketchfab、Hyper3D 等集成）与 API 凭据存放位置见官方文档 README.md；遇到问题可参考 SECURITY.md 了解遥测细节，或在项目仓库的 Issues 区提问。

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