内容
# blender-mcp
一款允许 AI 编程代理控制 Blender 的 MCP 服务器。26 种工具桥接您已经安装的 Blender MCP 插件（TCP 端口 9876）。还提供一个代理技能（`SKILL.md`），教导代理如何有效使用它们。
与任何支持 MCP 和代理技能的平台兼容 — Codex CLI、Grok Build、Cursor、Antigravity、Claude Code，可能还有其他您正在运行的平台。
CLI 变体工具启动一个无头后台 Blender，以检查磁盘上的 `.blend` 文件，而无需触及您的打开会话。
## 前提条件
1. Blender 5.1+，已安装并运行官方 Blender Lab MCP 扩展程序。这是来自 [blender.org/lab/mcp-server](https://www.blender.org/lab/mcp-server/) 的第一方扩展程序 — 在 Blender 中，前往 编辑 > 首选项 > 扩展程序 > 获取扩展程序，搜索"MCP"，安装它，启用它，然后在扩展程序的首选项面板中单击"启动 MCP 服务器"（默认 `localhost:9876`）。
注意：还有其他旧的社区 Blender+MCP 插件（不同的协议，不同的端口，不同的安装路径） — 本仓库专门与官方实验室扩展程序通信。如果您的设置与上述步骤不匹配，此服务器将无法连接。
2. Python 3.10+。为您的代理将启动此服务器的 Python 安装 `mcp` 包：
pip install mcp
3. 将此仓库克隆到磁盘上的某个位置。下面的设置指的是 `<repo>/blender_mcp_server.py` — 换成您的实际克隆路径。
## 各平台设置
每个平台都需要完成两件事情：注册 `blender_mcp_server.py` 作为 MCP 服务器，然后使 `skill/blender-mcp/SKILL.md` 可被代理发现，以便代理知道如何使用它。如果您的平台不支持技能，请跳过该部分。MCP 工具仍然有效 — 您只是失去了额外的指导。
### Codex CLI
将以下内容添加到 `config.toml`（默认 `~/.codex/config.toml` — 使用 `codex doctor` 检查 `CODEX_HOME` 如果您已自定义它）：
```toml
[mcp_servers.blender]
command = "python"
args = ["<repo>/blender_mcp_server.py"]
```
复制技能，以便 Codex 可以发现它：
<CODEX_HOME>/skills/blender-mcp/SKILL.md
验证：`codex mcp list` 应该显示 `blender`。`codex exec "Which skill do you have for Blender work?"` 应该提及 `blender-mcp`。
### Grok Build CLI
grok mcp add blender python -- <repo>/blender_mcp_server.py
将技能复制到 `~/.agents/skills/blender-mcp/SKILL.md`（下面的共享约定），或将其放入特定仓库的 `.agents/skills/blender-mcp/SKILL.md` 中。
验证：`grok mcp list` 和 `grok inspect` 应该都显示 `blender-mcp`。
### Cursor
将以下内容添加到 `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）：
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["<repo>/blender_mcp_server.py"]
}
}
}
```
将技能文件夹复制到项目中的 `.cursor/skills/blender-mcp/` 中。Cursor 会在下一次会话中获取它。
### Antigravity（CLI、IDE、Antigravity 2.0）
将以下内容添加到 `~/.gemini/config/mcp_config.json`：
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["<repo>/blender_mcp_server.py"]
}
}
}
```
将技能复制到 `~/.gemini/config/skills/blender-mcp/` — 这是 Antigravity 三种版本（CLI、IDE、2.0）都识别的唯一路径。项目范围的技能也有效，位于工作区内的 `.agents/skills/blender-mcp/` 中。
### 其他任意代理技能 / MCP 兼容平台
`SKILL.md` 是一种开放的、跨代理的标准 — Claude Code、Codex、Cursor 和 Antigravity 都读取相同的格式。将 `skill/blender-mcp/` 直接复制到代理读取的任意技能目录中通常有效。对于 MCP 注册，查找 `mcpServers`（JSON）或 `[mcp_servers.*]`（TOML）块并添加：
command: python
args: ["<repo>/blender_mcp_server.py"]
尝试 `.agents/skills/`（项目级）首先，如果您的平台未在上面列出。几个工具已经读取它作为共享约定。
## 使用
一旦 Blender 扩展程序的服务器正在运行，并且至少有一个平台已注册，只需要求您的代理执行 Blender 操作。技能会自动启动 — 您不需要提及它的名称：
- "在场景中添加一个立方体，将其缩放至 2m，并告诉我其尺寸。"
- "截取视口的截图。"
- "将选定的对象以 GLB 格式导出到 ~/Desktop/model.glb。"
`SKILL.md` 促使代理首先检查场景（`blender_get_objects_summary`），一次进行一个聚焦的更改，然后使用真实的数字进行验证，而不是仅仅盯着截图。需要直接使用特定的工具，而不涉及技能指导？直接调用它 — 例如，使用原始 `bpy` 代码的 `blender_execute_python`。
## 故障排除
**Codex 桌面应用程序无法在 Windows 上启动服务器。** 这与"无法连接到 localhost:9876 处的 Blender"错误不同 — 那只是意味着 Blender 尚未打开。这意味着 Python 进程根本没有启动。
Codex 在 Windows 上提供了两项内容：一个普通的 CLI 可执行文件，它继承了您的正常终端 PATH，以及一个 Store/MSIX 打包的桌面应用程序（`OpenAI.Codex`，通过 `Get-AppxPackage` 可见）。打包应用程序的环境可能比终端会话更受限制，因此即使相同的命令通过终端、Codex CLI 或 Grok Build CLI 工作正常，它也可能无法找到可用的 `python`。
最快的解决方法 — 安装 [uv](https://docs.astral.sh/uv/) 并让它提供一个 Python，打包应用程序可以可靠地找到：
uv python install
仍然找不到？直接将 MCP 配置的 `command` 指向 `uv` 安装的 Python，而不是使用裸 `python` 名称。
## 工具（26）
只读（19）：
- blender_get_blendfile_datablocks_summary (+ _cli)
- blender_get_blendfile_missing_files_summary (+ _cli)
- blender_get_blendfile_linked_libraries_summary (+ _cli)
- blender_get_blendfile_path_info_summary (+ _cli)
- blender_get_blendfile_usage_summary (+ _cli)
- blender_get_objects_summary
- blender_get_object_detail_summary
- blender_get_python_api_docs
- blender_get_window_screenshot （返回内联 PNG）
- blender_get_area_screenshot （返回内联 PNG）
- blender_get_screenshot_as_json
- blender_render_viewport_to_path
- blender_search_api_docs
- blender_search_user_manual
写入 / 状态更改（7）：
- blender_execute_python （强大的工具 - 任意 bpy 代码）
- blender_execute_python_cli （.blend 文件上的任意代码，无头）
- blender_switch_workspace
- blender_switch_matching_workspace
- blender_focus_object
- blender_focus_object_data
- blender_render_thumbnail_to_path
## 约定
- 交互式工具：执行的代码将 JSON 可序列化的字典分配给 `result`。
- CLI 工具：执行的代码将字典分配给 `summary`；对 `.blend` 文件的更改将被丢弃，除非代码调用 bpy.ops.wm.save_mainfile()。
- CLI 工具自动从正在运行的实例中检测 blender.exe；如果 Blender 已关闭，可以使用 BLENDER_BINARY 环境变量覆盖。
## 环境变量
BLENDER_MCP_HOST（默认 localhost），BLENDER_MCP_PORT（默认 9876），BLENDER_MCP_TIMEOUT（默认 120 秒），BLENDER_BINARY（blender.exe 的路径）。
## 注意
- 请求是短寿命的一次性连接。多个代理可以共享同一个 Blender 实例 — 只需不要同时从多个实例中触发繁重的操作。
- 截图工具以内联图像内容的形式返回图像。能够渲染图像的客户端可以直接看到您的视口。
