内容
# blendmcp
通过Claude和其他LLM控制Blender，使用模型上下文协议（MCP）。blendmcp允许AI助手检查和编辑Blender场景：创建和转换对象，应用材质，运行Python，捕获视口截图，从PolyHaven、Sketchfab、Hyper3D和Hunyuan3D导入资产。
[](https://pypi.org/project/blendmcp/)
[](https://pypi.org/project/blendmcp/)
[](LICENSE)
[](https://github.com/owenpkent/blendmcp/actions/workflows/tests.yml)
> **命名：** 全程使用一个名称。 **`blendmcp`** 是PyPI软件包、`uvx blendmcp` / `pip install blendmcp`命令、`import blendmcp`模块和GitHub仓库；Blender插件显示为 **BlendMCP**。
这是 [blender-mcp](https://github.com/ahujasid/blender-mcp) 由 [Siddharth Ahuja](https://x.com/sidahuj) 维护的无遥测分叉。 [原始教程视频](https://www.youtube.com/watch?v=lCyQ717DuzQ) （设置有所不同；请按照以下说明）。
## 快速入门
1. 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
2. 将服务器添加到MCP客户端（Claude Desktop、Cursor或VS Code）。最小配置：
```json
{ "mcpServers": { "blendmcp": { "command": "uvx", "args": ["blendmcp"] } } }
```
3. 安装Blender插件，然后连接：
```bash
uv tool install blendmcp
blendmcp install-addon
```
在Blender的3D视图侧栏（按 `N`），打开 **BlendMCP** 选项卡并点击 **连接到Claude**。
更多详细信息和其他客户端请参见下面的 [安装](#installation)。
## 版本说明
每个版本的完整历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。最新版本是 **1.4.3**。
### 此分叉新增功能
- 结构化编辑工具：`add_primitive`、`modify_object`、`set_material`、`duplicate_object` 和 `delete_object`。这些工具比生成原始Python更可靠，并且返回受影响对象的边界框和尺寸，因此一步即可确认结果。
- `batch_edit` 在单个回合中应用多个编辑操作，并带有每个操作的返回结果，用于批量更改。
- `get_blender_status` 报告连接状态和启用的集成。如果工具报告连接问题，请先调用它。
- `execute_blender_code` 接受 `return_screenshot=True` 以返回视口图像以及结果，并在代码失败时显示完整的Python回溯，以便进行纠正。
- 连接在套接字断开后重新连接并重试一次，因此在会话中重启Blender不会破坏下一次调用。
- 插件包含在软件包中，因此 `blendmcp install-addon` 将其保持与服务器相同的版本（版本握手会在版本漂移时发出警告）。
- 完全删除了遥测/数据收集代码；此分叉不会发送任何使用数据。
- 参见 `docs/claude-integration-improvements.md` 以获取理由和完整的更改列表。
### 从原始blender-mcp继承
- 查看Blender视口截图以更好地理解场景
- 使用Hunyuan3D和Hyper3D Rodin生成3D模型
- 搜索和下载Sketchfab模型
- Poly Haven资产支持（模型、纹理、HDRIs）
- 在远程主机上运行MCP服务器
### 安装新版本（现有用户）
- 对于新用户，您可以直接进入安装。对于现有用户，请参见以下几点
- 插件现在包含在 `blendmcp` 软件包中，因此服务器和插件一起更新。如果您已将服务器安装为uv工具，请使用以下命令更新两者：
```bash
uv tool upgrade blendmcp
blendmcp install-addon
```
然后重启Blender。 `blendmcp install-addon --list` 显示检测到的Blender版本； `--all` 安装到每个版本， `--blender-version 4.2` 针对特定版本。
- 喜欢手动操作？下载最新的 `src/blendmcp/addon.py` 并替换Blender中较旧的文件。
- 如果MCP客户端缓存了服务器，请删除并重新添加它（或重启客户端），以便它拾取新版本。
- `get_blender_status` 报告服务器和插件版本，并在插件过期时发出警告。
## 功能
- **双向通信**：通过基于套接字的服务器将Claude AI连接到Blender
- **结构化编辑工具**：通过专用工具添加基元、转换对象、设置材质、复制和删除，这些工具返回受影响对象的边界框和尺寸以进行确认
- **对象操作**：在Blender中创建、修改和删除3D对象
- **材质控制**：应用和修改材质和颜色
- **场景检查**：获取当前Blender场景的详细信息
- **视觉反馈**：捕获视口截图，包括与 `execute_blender_code` 结果一起
- **代码执行**：从Claude在Blender中运行任意Python代码
## 组件
系统由两个主要组件组成：
1. **Blender插件（`src/blendmcp/addon.py`）**：一个Blender插件，在Blender内创建套接字服务器以接收和执行命令
2. **MCP服务器（`src/blendmcp/server.py`）**：一个Python服务器，实现模型上下文协议并连接到Blender插件
## 安装
### 先决条件
- Blender 3.0或更新版本
- Python 3.10或更新版本
- uv包管理器：
**如果您在Mac上，请像这样安装uv**
```bash
brew install uv
```
**在Windows上**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
然后将uv添加到用户路径中（可能需要重启Claude Desktop）：
```powershell
$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）
示例：
```bash
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
```
### Claude for Desktop集成
[观看设置说明视频](https://www.youtube.com/watch?v=neoK_WMq92g) （假设您已经安装了uv）
前往Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json，包含以下内容:
```json
{
"mcpServers": {
"blendmcp": {
"command": "uvx",
"args": [
"blendmcp"
]
}
}
}
```
### Cursor集成
[](https://cursor.com/install-mcp?name=blendmcp&config=eyJjb21tYW5kIjoidXZ4IGJsZW5kbWNwIn0%3D)
对于Mac用户，请前往设置 > MCP并粘贴以下内容
- 要用作全局服务器，请使用“添加新全局MCP服务器”按钮并粘贴
- 要用作项目特定服务器，请在项目的根目录中创建 `.cursor/mcp.json` 并粘贴
```json
{
"mcpServers": {
"blendmcp": {
"command": "uvx",
"args": [
"blendmcp"
]
}
}
}
```
对于Windows用户，请前往设置 > MCP > 添加服务器，添加具有以下设置的新服务器：
```json
{
"mcpServers": {
"blendmcp": {
"command": "cmd",
"args": [
"/c",
"uvx",
"blendmcp"
]
}
}
}
```
[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%22blendmcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A5B%22blendmcp%22%5D%7D)
### 安装Blender插件
插件包含在 `blendmcp` 软件包中，因此您可以使用一个命令安装它，而不是下载文件。在将服务器安装为uv工具后：
```bash
uv tool install blendmcp # 如果您尚未安装
blendmcp install-addon
```
这会将插件复制到您的Blender插件文件夹中（使用 `--list` 查看检测到的Blender版本， `--all` 用于所有版本，或 `--blender-version 4.2` 用于特定版本）。然后打开Blender，前往 编辑 > 首选项 > 插件，并启用“界面：BlendMCP”。这样可以保持插件与服务器的版本一致，因为新工具需要匹配的插件版本。
**手动安装（替代方案）：**
1. 从此仓库下载 `src/blendmcp/addon.py`
2. 打开Blender
3. 进入 编辑 > 首选项 > 插件
4. 点击“安装...”并选择 `addon.py` 文件
5. 通过选中“界面：BlendMCP”旁边的复选框启用插件
## 用法
### 启动连接
1. 在Blender中，进入3D视图侧栏（如果不可见，请按 `N`）
2. 找到“BlendMCP”选项卡
3. 如果您想从Poly Haven API获取资产，请启用Poly Haven复选框（可选）
4. 点击“连接到Claude”
5. 确保MCP服务器在您的终端中运行
### 与Claude一起使用
一旦Claude的配置文件已设置好，并且Blender上的插件正在运行，您将看到带有Blender MCP工具的锤子图标。
#### 功能
- 获取场景和对象信息
- 通过专用工具添加基元并创建、删除、复制和修改形状以确认结果
- 为对象应用或创建材质
- 在Blender中执行任何Python代码（可选返回视口截图）
- 通过 [Poly Haven](https://polyhaven.com/) 下载正确的模型、资产和HDRIs
- 通过 [Hyper3D Rodin](https://hyper3d.ai/) 生成3D模型
### 示例命令
以下是您可以要求Claude执行的一些示例：
- “在地下城创建一个低多边形场景， guarded by a dragon guarding a pot of gold” [Demo](https://www.youtube.com/watch?v=DqgKuLYUv00)
- “使用HDRIs、纹理和模型（如岩石和植被）创建海滩氛围” [Demo](https://www.youtube.com/watch?v=I29rn92gkC4)
- 给定参考图像，从中创建Blender场景 [Demo](https://www.youtube.com/watch?v=FDRb03XPiRo)
- “通过Hyper3D生成一个花园侏儒的3D模型”
- “获取当前场景的信息，并从中创建一个threejs草图” [Demo](https://www.youtube.com/watch?v=jxbNI5L7AH8)
- “使这辆车变成红色和金属色”
- “创建一个球体并将其放在立方体上方”
- “使照明像工作室一样”
- “将相机指向场景并使其等轴测”
## Hyper3D集成
Hyper3D的免费试用密钥允许您每天生成有限数量的模型。如果达到每日限制，您可以等待第二天的重置或从hyper3d.ai和fal.ai获取自己的密钥。
## 故障排除
- **从这里开始**：请Claude运行 `get_blender_status`。它报告服务器是否可以访问Blender、哪些集成已启用以及插件是否已过期（并修复）。
- **连接问题**：确保Blender插件服务器正在运行（您在BlendMCP侧栏中点击了“连接到Claude”），并且MCP服务器已在Claude上配置。不要在终端中自己运行 `uvx` 命令；MCP客户端会启动它。有时第一个命令可能不会通过，但第二次就会开始工作。
- **插件过期**：升级服务器后，运行 `blendmcp install-addon` 并重启Blender。新工具需要匹配的插件版本。
- **超时错误**：尝试简化您的请求或将它们分解为更小的步骤。
- **Poly Haven集成**：Claude有时对其行为反应迟钝。
- **仍然卡住？**：重启Claude和Blender服务器。
## 技术细节
### 通信协议
系统使用基于JSON的简单协议通过TCP套接字：
- **命令** 作为带有 `type` 和可选 `params` 的JSON对象发送
- **响应** 作为带有 `status` 和 `result` 或 `message` 的JSON对象发送
## 限制和安全考虑
- `execute_blender_code` 工具允许在Blender中运行任意Python代码，这可能很强大但也可能很危险。请在生产环境中谨慎使用。 **请始终在使用前保存您的工作**。
- Poly Haven需要下载模型、纹理和HDRI图像。如果您不想使用它，请在Blender中取消勾选复选框。
- 复杂的运算可能需要分解为更小的步骤
- 要报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。
## 贡献
欢迎贡献！请随时提交拉取请求。
### 开发
测试位于 `tests/` 并在Blender外部运行。因为 `addon.py` 导入 `bpy`（仅在Blender内部可用），所以 `tests/conftest.py` 安装了 `bpy`、`mathutils` 和 `requests` 的轻量级替代品，以便可以直接导入和测试插件的纯帮助函数。
使用 [uv](https://docs.astral.sh/uv/) 安装开发依赖并运行测试套件：
```bash
uv sync --group dev
uv run pytest
```
测试涵盖了插件的Sketchfab尺寸归一化几何助手；服务器助手和工具（颜色归一化、环境配置、编辑工具、`get_blender_status`）；连接逻辑（重新连接一次并重试、代码执行回溯、批量编辑）；以及插件安装程序（Blender目录解析、安装/卸载以及确保插件版本与软件包版本匹配的守护程序）。## 致谢和免责声明
这是第三方集成，非Blender官方制作。 BlendMCP是 [blender-mcp](https://github.com/ahujasid/blender-mcp) 由 [Siddharth Ahuja](https://x.com/sidahuj) 维护的分叉，由 [Owen Kent](https://github.com/owenpkent) 维护。它保留原始的MIT许可证和版权。与上游不同，这个分叉不会收集任何遥测数据。
