内容
# blender-mcp-suite
**适用于Blender的模块化MCP服务器** — 通过Claude、Cursor、VS Code或任何MCP客户端控制Blender，包含9个按需加载的类别中的61种工具，支持确定性真实性验证和PolyHaven资产集成。
通过将Blender MCP生态系统中最好的想法结合成一个连贯、经过测试的套件而构建（参见[先前的工作](#先前的工作--致谢)）。
## 亮点
- **按需加载的工具类别** — LLM在启动时只看到15个核心工具；它按需启用`mesh_edit`、`materials`、`animation`、`geometry_nodes`、`render`、`polyhaven`等工具，通过`enable_tools`。在不牺牲功能的情况下保持模型的上下文小。`--eager`标志为不支持`tools/list_changed`的客户端预先注册所有内容。
- **真实性验证** — `scene_measure`（距离、表面间隙、边界框、网格统计）和`scene_assert`（变换、材质、修改器、边界）让模型**验证**其工作确定性，而不是从渲染中猜测。
- **视口截图和渲染结果作为图像返回** — 模型看到场景；无头Blender获得快速工作台渲染备用。
- **从设计上保证线程安全** — 插件的套接字线程从不触及`bpy`；每个命令通过`bpy.app.timers`排队的队列发送到Blender的主线程，超时时间不能使Blender崩溃。
- **可靠的线路协议** — TCP上的长度前缀JSON帧处理兆字节级图像有效载荷确定性，具有自动重新连接功能。
- **PolyHaven集成** — 搜索和下载免费CC0 HDRIs（自动世界设置）、PBR纹理集（自动材质连接）和模型（自动导入）。无需API密钥。下载在服务器进程中运行，不在Blender内部。
- **混合工具** — 一个工具通过`op`/`type`参数涵盖一系列操作，因此61种工具涵盖了原本需要150+种工具才能实现的表面。
## 要求
- Blender **4.2+** （在4.5 LTS上测试）
- Python **3.10+**
## 安装
### 1. 安装Python包
```bash
pip install git+https://github.com/iQreu/blender-mcp-suite.git
# 或从克隆仓库：
git clone https://github.com/iQreu/blender-mcp-suite.git
cd blender-mcp-suite
pip install .
```
### 2. 安装Blender插件
从[发布页面](https://github.com/iQreu/blender-mcp-suite/releases)下载`blender_mcp_suite_addon.zip`（或使用`python scripts/build_addon.py`构建），然后在Blender中：
**编辑 → 首选项 → 插件 → 从磁盘安装…** → 选择zip文件 → 启用 **Blender MCP Suite**。
或无头安装：`python scripts/install_addon.py`
### 3. 启动桥梁
在Blender的3D视口中按`N` → **MCP** 标签 → **启动服务器** （默认端口9876）。
### 4. 配置MCP客户端
Claude Desktop / Claude Code (`claude mcp add blender -- python -m blender_mcp_suite`) 或 JSON配置：
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["-m", "blender_mcp_suite"]
}
}
}
```
对于不支持动态工具列表更新的客户端（某些VS Code版本），在`args`中添加`"--eager"`。
环境变量：`BLENDER_MCP_HOST`、`BLENDER_MCP_PORT`、`BLENDER_MCP_EAGER`、`BLENDER_MCP_DISABLE_EXECUTE_CODE`、`BLENDER_MCP_TIMEOUT`、`BLENDER_MCP_DOWNLOAD_DIR`。
## 工具目录
### 核心（始终加载，15种）
| 工具 | 用途 |
|---|---|
| `ping_blender` | 健康检查，版本 |
| `scene_info` | 概览 / 对象 / 层次 / 统计 |
| `object_inspect` | 单个对象的完整详细信息 |
| `object_create` | 立方体，球体，圆柱体，平面，圆锥，环形，空对象，文本，曲线 |
| `object_modify` | 变换 / 重命名 / 父对象 / 可见性 / 原点（批处理） |
| `object_delete`、`object_duplicate`、`select_objects` | 对象管理 |
| `viewport_screenshot` | 查看场景（无头备用：快速渲染） |
| `scene_measure` | 距离，表面间隙，边界框，尺寸，顶点/面计数 |
| `scene_assert` | 对象存在，计数等于，变换接近，边界内，有材质，有修改器 |
| `history` | 撤销检查点 / 撤销 / 重做 |
| `execute_code` | 任意Python逃生阀（可禁用） |
| `enable_tools`、`list_tool_categories` | 延迟加载控制 |
### 延迟加载类别（46种工具）
| 类别 | 工具 |
|---|---|
| `mesh_edit` （8种） | 选择元素，挤出，插入/倒角，细分/环切，变换选择，合并/焊接，布尔运算，清理 |
| `materials` （7种） | Principled BSDF创建，分配，检查，着色器节点添加/连接/设置，一键PBR纹理设置 |
| `modifiers` （4种） | 添加，编辑，应用/删除，列表 |
| `animation` （6种） | 关键帧，多关键帧变换助手，时间线，F曲线平滑，动画状态预览，约束 |
| `geometry_nodes` （5种） | 分组，节点添加/连接，修改器输入，模板（散布，数组，曲线到网格） |
| `render` （4种） | 设置，静态渲染（返回图像），动画渲染，检查 |
| `lighting_camera` （5种） | 灯光，相机，自动帧对象，世界颜色/HDRI，景深 |
| `import_export` （3种） | 导入（obj/fbx/gltf/stl/usd/ply），导出，从.blend追加 |
| `polyhaven` （4种） | 搜索，HDRI下载（自动世界），纹理下载（自动材质），模型下载（自动导入） |
## 示例会话
> “启用材质和灯光工具，构建一个带有闪亮红色环形物体在平面上的小型场景，用PolyHaven的HDRI照明，并显示结果。”
模型调用`enable_tools(["materials", "lighting_camera", "polyhaven"])`，创建对象，使用`scene_measure`验证位置，下载HDRI，使用`camera_frame_objects`帧定相机，并返回`render_image` — 所有过程中都有真实性检查。
## 开发
```bash
pip install -e .[dev]
pytest # 单元测试（无需Blender）
pytest -m e2e # 端到端测试，针对真实无头Blender
python scripts/dev_link_addon.py # 将插件连接到Blender的插件目录
```
架构：
```
MCP客户端 ↔ 标准输入/输出 ↔ blender-mcp-suite（FastMCP）↔ TCP 127.0.0.1:9876
（4字节长度前缀JSON）↔ 插件套接字线程 ↔ 队列 + bpy.app.timers ↔ bpy（主线程）
```
## 先前的工作 / 致谢
该项目重新实现了（清洁室）和组合了先驱者的创意：
- [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) （MIT）— 插件 + TCP套接字架构和PolyHaven集成
- [PatrykIti/blender-ai-mcp](https://github.com/PatrykIti/blender-ai-mcp) （Apache 2.0）— 确定性测量/断言优于视觉猜测
- [youichi-uda/blender-mcp-pro](https://github.com/youichi-uda/blender-mcp-pro) — 带有急切回落的延迟工具类别加载
- [RFingAdam/mcp-blender](https://github.com/RFingAdam/mcp-blender) （AGPL；仅创意，无代码）— 主线程定时器调度，工具分类法
- [sandraschi/blender-mcp](https://github.com/sandraschi/blender-mcp) （MIT）— 混合工具设计
## 许可证
MIT — 参见 [LICENSE](LICENSE).
关于插件的说明：使用`bpy` API的Blender插件被Blender基金会视为GPL衍生品。MIT是GPL兼容的，因此这不会造成冲突，但当插件与Blender一起分发时，它实际上受GPL兼容条款的约束。
