内容
# blender-mcp-桥接
Blender 官方 MCP 插件（TCP 端口 9876）与 Claude Desktop / Claude Code（stdio MCP）之间的桥梁。
---
## 概要
### 开发动机
2026年6月目前，[Blender 官方 MCP 插件](https://lab.blender.org/mcp) 使用的是自定义的 TCP 协议（`{"type": "execute", "code": "..."}`），似乎并未实现标准 MCP（JSON-RPC 2.0）。而 Claude Desktop 只支持标准 MCP，因此我们创建了这个桥接。
### 目标
使标准 MCP 客户端（Claude Desktop / Claude Code / Gemini CLI 等）可以直接操作 Blender。
### 功能
通过 Claude Code 等 AI 代理的指令，可以对 Blender 的场景进行操作（创建对象、变换、设置材质）。
```
Claude Desktop / Claude Code
│ stdio (MCP JSON-RPC 2.0) ← Claude 可理解的格式
▼
blender-mcp-桥接 ← 该应用程序（转换和转发）
│ TCP socket (port 9876) ← Blender 插件可接受的格式
▼
Blender 插件
```
---
## 运行环境
### 前提条件
- Python 3.10 或以上
- [Blender 官方 MCP 插件](https://lab.blender.org/mcp)（需要在 Blender 中安装和启用）
### 支持平台
macOS / Windows
---
## 快速开始
### 从 GitHub 直接安装（推荐）
```bash
claude mcp add blender-mcp-桥接 \
--env BLENDER_HOST=localhost \
--env BLENDER_PORT=9876 \
-- uvx --from git+https://github.com/otinori/blender-mcp-bridge blender-mcp-桥接
```
`uvx` 将直接获取存储库并执行，因此无需克隆或使用 pip 安装。
### 使用设置脚本注册
```bash
# 克隆后执行
git clone https://github.com/otinori/blender-mcp-bridge
cd blender-mcp-桥接
python3 scripts/setup.py # 一键安装 MCP 库并注册到配置文件中
```
为每个客户端单独配置：
```bash
python3 scripts/setup_claude_desktop.py # Claude Desktop
python3 scripts/setup_claude_code.py # Claude Code (CLI)
python3 scripts/setup_gemini.py # Gemini CLI
python3 scripts/setup_vscode.py # VS Code（Continue / Copilot 等 MCP 兼容扩展）
python3 scripts/setup_codex.py # OpenAI Codex CLI
```
※ 由于环境限制，vscode 版本和 codex 版本的运行状况未经过验证。
---
## 主要用法
1. **安装并启用 Blender MCP 插件**。
2. **启动 Blender**（插件将在端口 9876 开始监听）。
3. **重启 Claude Desktop 或 Claude Code**。
4. 通过 Claude 询问“请告诉我 Blender 的场景信息”等。
可以通过 `BLENDER_HOST` / `BLENDER_PORT` 环境变量更改连接目标（主机/端口）。默认为 `localhost:9876`。
### 工具列表
| 工具名称 | 说明 |
|---|---|
| `blender_get_scene_info` | 返回活动场景的名称、对象数量和帧信息 |
| `blender_list_objects` | 返回场景中的对象列表（可按 `type` 过滤） |
| `blender_get_object` | 返回指定对象的位移、旋转、缩放和材质 |
| `blender_create_object` | 创建网格、光源、相机等 |
| `blender_delete_object` | 删除指定对象 |
| `blender_transform_object` | 修改对象的位移、旋转和缩放（可部分更新） |
| `blender_set_material` | 为对象设置 Principled BSDF 材质 |
| `blender_execute_python` | 在 Blender 中执行任意 Python 代码 |
---
## 结构
```
blender-mcp-桥接/
├── bridge.py # MCP 服务器本体（转换和 TCP 转发）
├── scripts/
│ ├── setup.py # 所有客户端的一键设置（交互式菜单）
│ ├── setup_claude_desktop.py # Claude Desktop
│ ├── setup_claude_code.py # Claude Code (CLI)
│ ├── setup_gemini.py # Gemini CLI
│ ├── setup_vscode.py # VS Code（所有 MCP 兼容扩展）
│ └── setup_codex.py # OpenAI Codex CLI
└── pyproject.toml
```
※ 由于环境限制，setup_vscode.py 和 setup_codex.py 的运行状况未经过验证。
---
## 许可证
Apache License 2.0 — 请参阅 [LICENSE](LICENSE)。
作为程序开发的实验，我们试用 OpenSpec。
因此，`.claude/skills/openspec-*` 和 `.claude/commands/opsx/*` 遵循 OpenSpec 许可证。
