ahujasid/blender-mcp

# BlenderMCP - Blender 模型上下文协议集成 BlenderMCP 将 Blender 与 Claude AI 通过模型上下文协议（MCP）连接起来，使 Claude 能够直接与 Blender 交互并控制它。此集成实现了提示辅助的 3D 建模、场景创建和操作。 **我们没有官方网站。任何在线看到的网站都是非官方的，与本项目无关。请自行承担风险使用。** [完整教程](https://www.youtube.com/watch?v=lCyQ717DuzQ) ## 当前版本 (1.5.5) - 新增 Hunyuan3D 支持 - 查看 Blender 视口截图以更好地理解场景 - 搜索并下载 Sketchfab 模型 - 通过其 API 支持 Poly Haven 资源 - 支持使用 Hyper3D Rodin 生成 3D 模型 - 在远程主机上运行 Blender MCP - 工具执行遥测（完全匿名） ### 安装新版本（现有用户） - 对于新用户，可以直接前往安装部分。对于现有用户，请参考以下要点： - 下载最新的 addon.py 文件并替换旧文件，然后将其添加到 Blender - 从 Claude 中删除 MCP 服务器并重新添加，应该就可以正常使用了！ ## 功能 - **双向通信**：通过基于套接字的服务器将 Claude AI 连接到 Blender - **对象操作**：在 Blender 中创建、修改和删除 3D 对象 - **材质控制**：应用和修改材质与颜色 - **场景检查**：获取当前 Blender 场景的详细信息 - **代码执行**：从 Claude 在 Blender 中运行任意 Python 代码 ## 组件 系统由两个主要组件组成： 1. **Blender 插件（`addon.py`）**：在 Blender 内部创建套接字服务器以接收和执行命令 2. **MCP 服务器（`src/blender_mcp/server.py`）**：实现模型上下文协议的 Python 服务器并连接到 Blender 插件 ## 安装 ### 先决条件 - Blender 3.0 或更高版本 - Python 3.10 或更高版本 - uv 软件包管理器： **如果你在 Mac 上，请按如下方式安装 uv** ``` brew install uv ``` **在 Windows 上** ``` powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` 然后将 uv 添加到 Windows 用户路径中（可能需要重启 Claude Desktop）： ``` $localBin = "$env:USERPROFILE\.local\bin" $userPath = [Environment]::GetEnvironmentVariable("Path", "User") [Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User") ``` 否则安装说明请参考其官方网站：[安装 uv](https://docs.astral.sh/uv/getting-started/installation/) **⚠️ 在安装 UV 之前不要继续操作** ### 环境变量 可以使用以下环境变量来配置 Blender 连接： - `BLENDER_HOST`：Blender 套接字服务器的主机地址（默认："localhost"） - `BLENDER_PORT`：Blender 套接字服务器的端口号（默认：9876） 示例： ``` export BLENDER_HOST='host.docker.internal' export BLENDER_PORT=9876 ``` ### Claude 桌面集成 [观看设置说明视频](https://www.youtube.com/watch?v=neoK_WMq92g)（假设你已经安装了 uv） 前往 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json 并添加以下内容： ``` { "mcpServers": { "blender": { "command": "uvx", "args": [ "blender-mcp" ] } } } ```

Claude Code

使用 Claude Code CLI 添加 Blender MCP 服务器： ``` claude mcp add blender uvx blender-mcp ```

### Cursor 集成 [](https://cursor.com/link/mcp%2Finstall?name=blender&config=eyJjb21tYW5kIjoidXZ4IGJsZW5kZXItbWNwIn0%3D) 对于 Mac 用户，前往设置 > MCP 并粘贴以下内容 - 作为全局服务器使用，请使用"添加新的全局 MCP 服务器"按钮并粘贴 - 作为项目特定服务器使用，在项目根目录下创建 `.cursor/mcp.json` 并粘贴 ``` { "mcpServers": { "blender": { "command": "uvx", "args": [ "blender-mcp" ] } } } ``` 对于 Windows 用户，前往设置 > MCP > 添加服务器，使用以下设置添加新服务器： ``` { "mcpServers": { "blender": { "command": "cmd", "args": [ "/c", "uvx", "blender-mcp" ] } } } ``` [Cursor 设置视频](https://www.youtube.com/watch?v=wgWsJshecac) **⚠️ 只能运行一个 MCP 服务器实例（在 Cursor 或 Claude Desktop 中，不能同时运行两者）** ### Visual Studio Code 集成 _前提条件_：确保在继续之前已安装 [Visual Studio Code](https://code.visualstudio.com/)。 [](vscode:mcp/install?%7B%22name%22%3A%22blender-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22blender-mcp%22%5D%7D) ### 安装 Blender 插件 1. 从本仓库下载 `addon.py` 文件 2. 打开 Blender 3. 进入 编辑 > 偏好设置 > 插件 4. 点击"安装..."并选择 `addon.py` 文件 5. 勾选"界面：Blender MCP"旁边的框以启用插件 ## 用法 ### 建立连接  1. 在 Blender 中，进入 3D 视图侧边栏（按 N 如果不可见） 2. 找到 "BlenderMCP" 选项卡 3. 如果需要，从 Poly Haven 获取资源，请勾选 Poly Haven 复选框（可选） 4. 点击"连接到 Claude" 5. 确保 MCP 服务器正在终端中运行 ### 与 Claude 一起使用 一旦在 Claude 上设置了配置文件，并且在 Blender 上运行了插件，你将看到带有 Blender MCP 工具的锤子图标。  #### 功能 - 获取场景和对象信息 - 创建、删除和修改形状 - 为对象应用或创建材质 - 在 Blender 中执行任意 Python 代码 - 通过 [Poly Haven](https://polyhaven.com/) 下载正确的模型、资源和 HDRI - 通过 [Hyper3D Rodin](https://hyper3d.ai/) 生成 AI 3D 模型 ### 示例命令 以下是一些可以要求 Claude 执行的操作示例： - "在地下城中创建一个低多边形场景，并有一个守护金子的龙" [演示](https://www.youtube.com/watch?v=DqgKuLYUv00) - "使用 HDRI、纹理以及来自 Poly Haven 的岩石和植被等模型创建海滩氛围" [演示](https://www.youtube.com/watch?v=I29rn92gkC4) - 提供参考图像并从中创建 Blender 场景 [演示](https://www.youtube.com/watch?v=FDRb03XPiRo) - "通过 Hyper3D 生成 3D 模型" - "获取当前场景信息，并从中创建一个 threejs 草图" [演示](https://www.youtube.com/watch?v=jxbNI5L7AH8) - "将这款车变成红色且具有金属质感" - "创建一个球体并将其放置在立方体上方" - "让灯光像摄影棚一样" - "将相机指向场景，并使其成为等轴测视角" ## Hyper3D 集成 Hyper3D 的免费试用密钥允许你每天生成有限数量的模型。如果达到每日限制，你可以等待次日重置，或者从 hyper3d.ai 和 fal.ai 获取自己的密钥。 ## 故障排除 - **连接问题**：确保 Blender 插件服务器正在运行，并且 MCP 服务器已在 Claude 中配置。不要在终端中运行 uvx 命令。有时第一个命令无法通过，但之后就会开始工作。 - **超时错误**：尝试简化请求或将其分解为更小的步骤 - **Poly Haven 集成**：Claude 有时行为不稳定 - **是否尝试过重启？**：如果仍然存在连接错误，请尝试重新启动 Claude 和 Blender 服务器 ## 技术细节 ### 通信协议 系统使用基于 TCP 套接字的简单 JSON 协议： - **命令**：以包含 `type` 和可选 `params` 的 JSON 对象形式发送 - **响应**：以包含 `status` 和 `result` 或 `message` 的 JSON 对象形式返回 ## 限制与安全考虑 - `execute_blender_code` 工具允许在 Blender 中运行任意 Python 代码，这功能强大但可能存在危险。请谨慎在生产环境中使用。使用前务必保存工作。 - Poly Haven 需要下载模型、纹理和 HDRI 图像。如果你不想使用它，请在 Blender 中的复选框中关闭它。 - 复杂操作可能需要分解为更小的步骤 #### 遥测控制 BlenderMCP 收集匿名使用数据以帮助改进工具。你可以通过以下两种方式控制遥测： 1. **在 Blender 中**前往 编辑 > 偏好设置 > 插件 > Blender MCP 并取消勾选遥测同意复选框 - 同意（已勾选）：收集匿名提示、代码片段和截图 - 不同意（未勾选）：仅收集最小的匿名使用数据（工具名称、成功/失败、持续时间） 2. **环境变量**：通过运行以下命令完全禁用所有遥测： ``` DISABLE_TELEMETRY=true uvx blender-mcp ``` 或者将其添加到你的 MCP 配置中： ``` { "mcpServers": { "blender": { "command": "uvx", "args": ["blender-mcp"], "env": { "DISABLE_TELEMETRY": "true" } } } } ``` 所有遥测数据都经过完全匿名化处理，仅用于改进 BlenderMCP。 ## 贡献 欢迎贡献！请随时提交 Pull Request。 ## 免责声明 这是一个第三方集成，并非由 Blender 官方制作。由 [Siddharth](https://x.com/sidahuj) 制作

标签：3D场景创建, 3D建模, 3D资产下载, AI 集成, Blender, Blender插件, Claude AI, DNS解析, Homebrew安装, Hyper3D Rodin, MCP, Poly Haven, Python, SEO: 3D建模工具, SEO: AI辅助设计, SEO: Blender AI, Sketchfab, Socket通信, 代码执行, 场景检视, 对象操纵, 开源项目, 提示词辅助建模, 无后门, 服务器端编程, 材质控制, 模型上下文协议, 远程执行, 逆向工具, 遥测