内容
# mcp-blender-agent
> 适用于 AI 编程代理的完整 Blender 控制面板 — MCP 服务器为 Claude Code、GitHub Copilot、Cursor 和任何支持 MCP 的代理提供对 Blender 会话的完全控制：建模、绑定、动画、材质、着色器/几何节点、渲染和细粒度导出到 FBX / glTF / USD / Alembic。
与 [PoBruno/mcp-unreal-agent](https://github.com/PoBruno/mcp-unreal-agent) 是姊妹项目。相同的架构，相同的合约，相同的工具链 — Blender 的双胞胎。
---
## ⚡ 一键安装
在编辑器中打开您的项目，然后将匹配的提示粘贴到代理聊天中。MCP 服务器直接从 npm 通过 `npx` 运行 — **无需克隆，无需构建**。Blender 插件 zip 文件捆绑在 npm 包中；代理将打印其路径，以便您可以在 Blender 的插件 UI 中安装它。先决条件：**Blender 4.2 LTS+（推荐 5.x）**，**Node 18+**。
### Claude Code
```
在当前工作空间中安装 @pobruno/blender-agent。阅读 https://github.com/PoBruno/mcp-blender-agent 中的 install/AGENT-INSTALL.md 并运行所有阶段。合并
{ "command": "npx", "args": ["-y", "@pobruno/blender-agent@latest"] } 到
.mcp.json，然后运行 `npx -y @pobruno/blender-agent --print-skill-dir` 并复制
捆绑的 SKILL/FLOWS/TOOLS markdown 到 .claude/skills/blender-agent/。
将 MANAGED-BLOCK.md 中的托管块注入 CLAUDE.md。在任何破坏性操作之前使用
AskUserQuestion。打印 `--print-addon-zip` 的路径，以便我可以在 Blender 的插件 UI 中安装它。
```
### GitHub Copilot (VS Code)
```
在当前工作空间中安装 @pobruno/blender-agent。阅读 https://github.com/PoBruno/mcp-blender-agent 中的 install/AGENT-INSTALL.md 并运行所有阶段。合并
{ "command": "npx", "args": ["-y", "@pobruno/blender-agent@latest"] } 到
.vscode/mcp.json，然后运行 `npx -y @pobruno/blender-agent --print-skill-dir`
并复制捆绑的 instructions.md 到 .github/instructions/blender-agent.instructions.md
以及 FLOWS/TOOLS 到 .github/instructions/blender-agent/。将托管块从
MANAGED-BLOCK.md 注入 .github/copilot-instructions.md。在任何破坏性操作之前使用
AskUserQuestion。打印 `--print-addon-zip` 的路径，以便我可以在 Blender 的插件 UI 中安装它。
```
### Cursor
```
在当前工作空间中安装 @pobruno/blender-agent。阅读 https://github.com/PoBruno/mcp-blender-agent 中的 install/AGENT-INSTALL.md 并运行所有阶段。合并
{ "command": "npx", "args": ["-y", "@pobruno/blender-agent@latest"] } 到
.mcp.json，然后运行 `npx -y @pobruno/blender-agent --print-skill-dir` 并复制
捆绑的 SKILL/FLOWS/TOOLS markdown 到 ./blender-agent/。将托管块从
MANAGED-BLOCK.md 注入 AGENTS.md。在任何破坏性操作之前询问。打印
`--print-addon-zip` 的路径，以便我可以在 Blender 的插件 UI 中安装它。
```
### Claude Desktop
```
为我安装 @pobruno/blender-agent。阅读 https://github.com/PoBruno/mcp-blender-agent 中的 install/AGENT-INSTALL.md 并运行所有阶段。合并
{ "command": "npx", "args": ["-y", "@pobruno/blender-agent@latest"] } 到
%APPDATA%\Claude\claude_desktop_config.json。告诉我何时需要重启
Claude Desktop。在任何破坏性操作之前询问。打印 `npx -y @pobruno/blender-agent --print-addon-zip`
的路径，以便我可以在 Blender 的插件 UI 中安装它。
```
您需要手动执行的一个步骤：通过 Blender → 编辑 → 首选项 → 插件 → 安装... 安装 `BlenderAgent.zip`（`--print-addon-zip` 打印的路径）— 代理无法访问单独的 Blender 进程以启用插件。
安装后，代理在每次 3D 请求时读取捆绑的 `SKILL.md` — 因此它始终知道它驱动 Blender，启动并运行查看和完善循环。手动安装参考：[install/INSTALL.md](install/INSTALL.md)。更多复制粘贴工作流提示：[install/PROMPT-TEMPLATES.md](install/PROMPT-TEMPLATES.md)。
---
## 为什么存在
目前，Blender MCP 空间主要由 **创意玩具** 占据：“创建一个地下城场景”，“应用红色金属材质”。这些存在（参见 [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp)，22k+ 星）并且非常适合创意构思。
`blender-agent` 不同。它是一个 **生产控制面板**：
- 每个 Blender 操作符和 `bpy.data` 突变都表现为具有 Zod 输入模式和结构化输出的键入 MCP 工具。
- 复合原子流在单个撤销推送中包装多步骤突变。
- ID 链接使多工具工作流感觉像数据流 — 代理端无需字符串解析。
- 细粒度导出 — `bpy.ops.export_scene.fbx` / `export_scene.gltf` / `wm.usd_export` / `wm.alembic_export` 的每个参数都是工具输入，而不是黑盒。
- 安装程序检测用户的代理工具链（Claude / Copilot / Cursor / Claude Desktop）并配置自身。
- 被动上下文技能 — 始终在线的指导，代理在触摸 Blender 之前读取，以便它选择正确的工具。
代理应该能够描述一个低多边形角色 — 骨骼、权重、套接字、闲置动画、顶点命名、尺寸、纹理布局、导出目标 — 并端到端构建它。
---
## 您获得的内容
两个部分，镜像 `mcp-unreal-agent`：
- **`BlenderAgent/` — Python 插件**，位于 Blender 内部（或通过 `blender --background` 无头运行）。在端口 `9877` 上托管 HTTP 服务器（与主导的 `blender-mcp` 插件在 9876 上的不同 — 它们共存）。直接调用 `bpy.data`、`bpy.ops`、`bmesh`、`mathutils`。无构建步骤。
- **`Tools/` — TypeScript MCP 服务器。** 将来自代理的 MCP 工具调用转换为对插件的 HTTP 调用。提供结构化工具合约、ID 链、错误注册表、安装程序和被动上下文技能。
两种服务模式：
- **插件（首选）：** Blender 打开时自动启动。零开销。
- **无头：** 当未检测到 Blender 实例时，由 TS 服务器启动。用于 CI、批量操作和首次安装验证。
---
## 状态
**冲刺 0–6 已交付。Blender 5.1.2 的 v1.0 候选版本。** 插件（41 个处理程序模块，212 个路由），TS 服务器（20 个工具文件，约 216 个 MCP 工具），完整的集成套件 — **211 个用例通过** 在真正的 Blender 5.1.2 上（Steam 安装，端口 9877 与 ahujasid 的 `blender-mcp` 在 9876 上共存）。作为 `@pobruno/blender-agent` npm 包分发（服务器 + 捆绑的 Blender 插件 zip + 被动上下文技能）；GitHub Actions 在 `main` 标签推送时发布。 通过 `npx -y @pobruno/blender-agent@latest` 一键安装。参见 [.claude/docs/SPRINTS.md](.claude/docs/SPRINTS.md) 了解每个任务的完成日志。
---
## 快速开始（手动 — 适用于贡献者）
```powershell
git clone https://github.com/PoBruno/mcp-blender-agent.git
cd mcp-blender-agent/Tools
npm install
npm run build
npm run build:addon-zip
# 需要 Blender 4.2 LTS 或更新版本（推荐 5.x）才能运行集成测试：
npm test
```
最终用户：使用上面的“一键安装” — `npx` 获取已发布的包，无需克隆。
最终用户安装参考：[install/INSTALL.md](install/INSTALL.md)。代理驱动的安装手册：[install/AGENT-INSTALL.md](install/AGENT-INSTALL.md)。复制粘贴提示：[install/PROMPT-TEMPLATES.md](install/PROMPT-TEMPLATES.md)。
---
## 文档
- **[OBJECTIVES.md](OBJECTIVES.md)** — 我们正在构建的内容、原因、成功标准和非目标。
- **[ROADMAP.md](ROADMAP.md)** — 5 阶段交付计划和里程碑。
- **[CLAUDE.md](CLAUDE.md)** — 代理入口点。技术栈、约定、命令、文档索引。先阅读。
- **[AGENTS.md](AGENTS.md)** — Cursor 和其他代理的通用桥梁。
- **[.github/copilot-instructions.md](.github/copilot-instructions.md)** — GitHub Copilot 工具链（委托给 CLAUDE.md）。
- **[.claude/docs/ARCHITECTURE.md](.claude/docs/ARCHITECTURE.md)** — 系统圣经。
- **[.claude/docs/DECISIONS.md](.claude/docs/DECISIONS.md)** — ADRs。
---
## 参考仓库
只读克隆位于 `ref/` 下（gitignored）。它们存在于代理和开发人员可以研究先前艺术：
- `ref/blender-mcp/` — [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp)，主导的 Blender MCP。插件套接字模式和 Claude Desktop 集成的参考。
- `ref/blender-ai-mcp/` — [PatrykIti/blender-ai-mcp](https://github.com/PatrykIti/blender-ai-mcp)，目标优先路由和精选工具。生产型工具设计的参考。
要刷新：
```powershell
cd ref
git -C blender-mcp pull
git -C blender-ai-mcp pull
```
我们 **永远不会** 直接复制这些代码。我们研究，获取灵感，并根据我们的合约构建自己的。
---
## 许可证
MIT。参见 [LICENSE](LICENSE)。
与 Blender 基金会无关。“Blender” 是 Blender 基金会的商标。
MCP 市场