内容
<div align="center">
<img src="assets/logo.svg" width="760" alt="Blender MCP 增强版" />
### 打造世界。直接使用 Blender。创造不可能。
`建模` · `材质` · `动画` · `渲染` · `自动化`
[**English**](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)
[](https://github.com/XUJL-916/blender-mcp-enhanced/releases)
[](docs/COMPATIBILITY_BLENDER_5_1_2.md)
[](pyproject.toml)
[](tests)
[](LICENSE)
</div>
> **Blender MCP 增强版** 将 Blender 转变为一个适合代理的 3D 生产环境。AI 客户端通过模型上下文协议进行通信，而本地 Blender 插件执行结构化建模、材质、动画、渲染、资产操作和持久的后台作业。
封面是项目概念艺术。以下展示中的每个图像都是在开发和测试该项目时创建的 `.blend` 场景的实际渲染。
## 查看它如何构建
<div align="center">
<a href="assets/showcase/showreel.mp4">
<img src="assets/showcase/showreel.gif" width="820" alt="Blender MCP 增强版演示视频" />
</a>
<br />
<sub>点击动画以获取轻量级 MP4 版本。</sub>
</div>
<br />
<table>
<tr>
<td width="50%" align="center">
<img src="assets/showcase/future-city.png" alt="程序化未来城市" />
<br /><strong>霓虹未来城市</strong><br />
程序化方块、发光建筑、相机和灯光。<br />
<a href="mcp_future_city.blend">打开 .blend 场景</a>
</td>
<td width="50%" align="center">
<img src="assets/showcase/nanchang-blue-hour.png" alt="南昌蓝调城市研究" />
<br /><strong>南昌蓝调</strong><br />
一个结合现代天际线和传统亭子的城市研究。<br />
<a href="nanchang_city.blend">打开 .blend 场景</a>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<img src="assets/showcase/character-model.png" width="46%" alt="详细风格化角色模型" />
<br /><strong>详细角色研究</strong><br />
分层硬表面形式、材质、摄影棚灯光和特写细节。<br />
<a href="detailed_character.blend">打开 .blend 场景</a>
</td>
</tr>
</table>
## 为什么选择这个分支
该项目保持了原始 Blender MCP 桥接的直接性，并将其扩展为一个更完整的生产工具包：
| 领域 | 包含内容 |
|---|---|
| 结构化建模 | 网格编辑、修改器、雕塑助手、UV 工具、布尔运算、曲线、排版和测量 |
| 外观开发 | PBR 材质、完整的节点图编辑、灯光阵列、渲染通道和合成器控制 |
| 动画 | 关键帧、动作、约束、骨骼、角色绑定和 Blender 5.x FCurve 兼容性 |
| 场景制作 | 相机、集合、导入/导出、打包、清理、快照、差异和回滚感知配方 |
| 长时间作业 | 异步渲染、烘焙和下载队列，带有暂停/恢复、优先级、重试和重启恢复 |
| 工作流编排 | 依赖 DAG、CPU/GPU 槽、持久事件光标和结构化错误 |
| 资产生态系统 | Poly Haven、Sketchfab、BlenderKit、Hyper3D 和 Hunyuan3D 集成表面 |
## 想象提示
相同的工具表面可以驱动精确的硬表面工作或大型环境研究。这些是代表性的工作流提示，而不是一键式预设场景：
```text
在蓝调时段创建一个电影般的南昌海滨。先阻塞天际线，然后添加传统的亭子、桥梁灯光、河流反射、三个相机选项，并使用 Cycles 渲染选定的视图。
```
```text
从确定性种子创建一个张家界启发的砂岩柱地形。添加侵蚀掩码、森林分布、大气深度、悬崖路径，并排队三个相机渲染，每个 GPU 资源限制为 1。
```
```text
从 DEM 高程数据生成地形研究，构建 LOD 变体，烘焙法线和环境遮挡图，包装依赖项，并导出干净的 GLB。
```
## 架构
```mermaid
flowchart LR
A["AI 客户端"] -->|"MCP 工具"| M["Python MCP 服务器"]
M -->|"结构化 TCP 协议"| B["Blender 插件"]
B --> S["场景 + bpy"]
B --> Q["持久作业队列"]
Q --> C["CPU 工作线程"]
Q --> G["GPU 工作线程"]
Q --> E["事件日志"]
B --> X["外部资产服务"]
```
- **243 个通过测试**，涵盖协议、恢复、建模和生产工具。
- 请求/响应限制、编辑敏感日志记录和结构化错误。
- 上下文保留和回滚感知多步骤操作。
- Blender 5.1.2 是主要的验证目标；MCP 服务器支持 Python 3.10+。
## 快速入门
### 1. 安装 Python 服务器
```bash
git clone https://github.com/XUJL-916/blender-mcp-enhanced.git
cd blender-mcp-enhanced
uv sync
```
`pip install -e .` 也适用于 Python 3.10 或更高版本。
### 2. 安装 Blender 插件
1. 打开 **Blender > 编辑 > 首选项 > 插件**。
2. 选择 **从磁盘安装** 并选择 [`addon.py`](addon.py)。
3. 启用 **Blender MCP**。
4. 打开 Blender MCP 边栏面板并在端口 `9876` 启动本地服务器。
### 3. 注册 MCP 服务器
在 MCP 客户端配置中使用绝对路径：
```json
{
"mcpServers": {
"blender": {
"command": "uv",
"args": [
"--directory",
"C:/absolute/path/to/blender-mcp-enhanced",
"run",
"blender-mcp"
]
}
}
}
```
在请求客户端使用 Blender 工具之前，请启动 Blender 的插件服务器。
## 异步生产队列
长时间渲染、纹理烘焙和下载不需要阻塞主 Blender 连接。作业公开进度、输出、限定日志和持久状态。
```text
submit_async_job(kind="render", priority=50, resource="gpu", ...)
pause_async_job(job_id="...")
resume_async_job(job_id="...")
get_async_job_graph()
subscribe_async_job_events(after=cursor)
```
队列通过 `depends_on` 支持依赖关系、指数重试、CPU/GPU 并发限制和异常 Blender 重启后的恢复。有关完整合同，请参见 [生产工作流](docs/PRODUCTION_WORKFLOWS.md)。
## 文档
| 指南 | 目的 |
|---|---|
| [用户指南](docs/USER_GUIDE.md) | 安装和日常工作流 |
| [API 文档](docs/API_DOCUMENTATION.md) | 工具和协议参考 |
| [精细建模](docs/FINE_MODELING.md) | 精确建模工具表面 |
| [生产工作流](docs/PRODUCTION_WORKFLOWS.md) | 队列、回滚、渲染和打包 |
| [Blender 5.1 兼容性](docs/COMPATIBILITY_BLENDER_5_1_2.md) | 验证的 API 行为 |
| [故障排除](docs/TROUBLESHOOTING.md) | 连接和运行时诊断 |
| [开发人员指南](docs/DEVELOPER_GUIDE.md) | 架构和贡献说明 |
## 开发
```powershell
.\.venv\Scripts\python.exe -m py_compile addon.py src\blender_mcp\server.py
.\.venv\Scripts\python.exe -m pytest tests -q
```
一些集成工作流需要运行的 Blender 实例。本地 API 密钥位于环境变量或未跟踪的 `src/blender_mcp/config.py` 中。从 [`config.py.example`](src/blender_mcp/config.py.example) 开始。
## 安全
这是一个强大的本地自动化桥。`execute_blender_code` 可以在 Blender 中执行 Python，作业工具可以访问本地路径。请将 TCP 插件绑定到受信任的本地环境中，不要直接将其暴露给公共互联网，并且永远不要提交 API 密钥。
## 致谢和许可证
Blender MCP 增强版在 [MIT 许可证](LICENSE) 下发布。它建立在 [Siddharth Ahuja / ahujasid](https://github.com/ahujasid/blender-mcp) 和更广泛的 Blender MCP 社区的工作基础上。
<div align="center">
**从单个对象到整个世界，保持创造性循环在 Blender 中。**
[报告问题](https://github.com/XUJL-916/blender-mcp-enhanced/issues) ·
[探索文档](docs/USER_GUIDE.md) ·
[观看演示](assets/showcase/showreel.mp4)
</div>
