内容
# BlockbenchMCP
> 让 AI 直接在 [Blockbench](https://www.blockbench.net/) 中构建 Minecraft 模型、纹理和动画 — 通过 [模型上下文协议](https://modelcontextprotocol.io/)。
BlockbenchMCP 为 AI 助手提供了一个与正在运行的 Blockbench 窗口的实时连接。模型可以从启动屏幕开始一个项目，构建几何体（骨骼 + 立方体），**程序化绘制纹理**，创作 **关键帧动画**（包括 [GeckoLib](https://github.com/bernie-g/geckolib)），**安装 Blockbench 插件**，移动相机，并 **截图以便查看和完善自己的作品** — 所有这些都不需要您触摸编辑器。
<!-- Tip: add a screenshot or gif of a generated model here, e.g.  -->
它曾用于从单个提示创建、纹理和动画一个完整的 GeckoLib 灰熊（行走 / 跑步 / 睡觉 / 攻击）- 端到端。
---
## 目录
- [工作原理](#工作原理)
- [功能](#功能)
- [要求](#要求)
- [安装](#安装)
- [连接您的 AI 客户端](#连接您的AI客户端)
- [工具参考](#工具参考)
- [示例：动画 GeckoLib 熊](#示例动画GeckoLib熊)
- [故障排除](#故障排除)
- [安全](#安全)
- [限制](#限制)
- [开发](#开发)
- [许可证](#许可证)
---
## 工作原理
有两个部分：
| 部分 | 运行位置 | 责任 |
|-------|-----------|----------------|
| **桥接插件** — [`plugin/blockbench_mcp.js`](plugin/blockbench_mcp.js) | 在 Blockbench（桌面）中 | 在 `127.0.0.1:8787` 上托管本地 HTTP 端点（基于 Node 的 `net` 模块），并在渲染线程上针对 Blockbench API 运行每个命令。 |
| **MCP 服务器** — [`src/`](src/) → `dist/` | 您的 AI 客户端启动的 Node 进程 | 通过 stdio 传输公开 Blockbench 作为 MCP 工具，并将每个调用转发到桥接。 |
```
┌────────────┐ stdio (MCP) ┌──────────────────┐ HTTP 127.0.0.1:8787 ┌─────────────────────┐
│ AI 客户端 │ ──────────────▶ │ blockbench-mcp │ ──────────────────────▶ │ Blockbench + 插件 │
│ （Claude…） │ ◀────────────── │ （Node 服务器） │ ◀────────────────────── │ （实时编辑器） │
└────────────┘ └──────────────────┘ └─────────────────────┘
```
## 功能
- 🧱 **建模** — 创建骨骼（组）和立方体，一次一个或 **批量**（`add_groups` / `add_cubes` 一次构建整个姿势的骨架），具有完整的旋转和膨胀；编辑/移动/重新父节点/删除，并读取大纲树。
- 🎨 **纹理** — 创建纹理，程序化绘制纹理（像素，矩形，线条，圆圈，**椭圆，多边形，抖动，噪声**），**自动为每个立方体面着色** 使用 `detail_cubes` （无扁平或无纹理的间隙），并在 **面相对坐标** 中放置特征使用 `paint_faces`。
- 🎬 **动画** — 创建动画，为任何骨骼/通道批量添加关键帧，具有插值控制（线性 / catmullrom / 步进 / bezier）。
- 📸 **视觉** — `screenshot`， **`screenshot_views`** （一次多个角度）和 `get_texture` 内联返回图像，以便模型可以 *看到* 并迭代，并且 `check_model` 审计问题。
- 🧠 **指导** — `get_guide` 返回一个建模/纹理手册，以便 AI 构建详细的，旋转的模型，而不是几个扁平的盒子。
- 🧩 **插件** — 搜索，安装（通过商店 ID，URL 或文件）和卸载 Blockbench 插件，以便 AI 可以设置像 GeckoLib 这样的格式。
- 🔧 **逃生口** — `execute_script` 运行任意 Blockbench JS 以完成任何未被专用工具覆盖的功能。
- 🟢 **40 种工具**，全部通过单个本地连接。
## 要求
- **Blockbench 桌面应用程序**，版本 **4.8+** （网页应用程序无法托管桥接 - 参见 [限制](#限制)）。
- **Node.js 18+** （用于全局 `fetch`）。
- 一个具有 MCP 功能的客户端（Claude Code，Claude Desktop，Cursor 等）。
## 安装
### 1. 在 Blockbench 中安装桥接插件
1. 打开 **桌面** Blockbench 应用程序。
2. **文件 ▸ 插件 ▸ 从文件加载插件** 并选择 [`plugin/blockbench_mcp.js`](plugin/blockbench_mcp.js)。
*(或者将其复制到您的 Blockbench `plugins` 文件夹中。)*
3. 首次启动时，插件会请求 **网络权限** （它需要 `net` 模块来托管本地服务器）。选择 **“对此插件始终允许。”**
4. 一个 toast 消息确认 **“MCP 服务器已在端口 8787 上启动。”**
- 随时切换服务器：**工具 ▸ 启动 / 停止 MCP 服务器**
- 更改端口：**设置 ▸ 常规 ▸ MCP 服务器端口** （默认 `8787`）
验证它是否启动：
```bash
curl http://127.0.0.1:8787/ping
# {"ok":true,"protocol":1,"blockbench_version":"5.x.x","is_app":true,"has_project":false}
```
### 2. 构建 MCP 服务器
```bash
git clone https://github.com/sosadly/blockbench-mcp.git
cd blockbench-mcp
npm install
npm run build
```
## 连接您的 AI 客户端
将您的客户端指向 `dist/index.js` 通过 stdio。使用 **绝对路径**。
**Claude Code** — `.mcp.json` 在您的项目中（或 `claude mcp add`）：
```json
{
"mcpServers": {
"blockbench": {
"command": "node",
"args": ["/absolute/path/to/blockbench-mcp/dist/index.js"],
"env": { "BLOCKBENCH_MCP_PORT": "8787" }
}
}
}
```
**Claude Desktop** — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"blockbench": {
"command": "node",
"args": ["C:\\path\\to\\blockbench-mcp\\dist\\index.js"]
}
}
}
```
| 环境变量 | 默认值 | 用途 |
|---------|---------|---------|
| `BLOCKBENCH_MCP_PORT` | `8787` | 必须与插件的端口设置匹配。 |
| `BLOCKBENCH_MCP_HOST` | `127.0.0.1` | 桥接主机。 |
## 工具参考
| 组 | 工具 |
|-------|-------|
| **状态和指导** | `get_status`，`get_guide`，`list_formats` |
| **项目** | `new_project`，`set_project_meta`，`save_project`，`export_project`，`load_project`，`close_project` |
| **几何体** | `add_group`，`add_cube`，`add_groups`，`add_cubes`，`edit_element`，`delete_element`，`list_outliner`，`get_element`，`check_model` |
| **UV 和纹理** | `create_texture`，`paint_texture`，`detail_cubes`，`paint_faces`，`apply_texture`，`set_cube_uv`，`import_texture`，`resize_texture`，`list_textures`，`get_texture` |
| **动画** | `create_animation`，`add_keyframe`，`add_keyframes`，`list_animations`，`remove_animation` |
| **视图** | `set_camera_angle`，`screenshot`，`screenshot_views` |
| **插件** | `list_plugins`，`install_plugin`，`uninstall_plugin` |
| **逃生口** | `execute_script` |
约定：坐标为 **Blockbench 单位**；旋转为 **度**；纹理像素操作使用 **左上角原点，y 指向下**。`add_cube` 返回每个面的解析 UV 矩形；`detail_cubes` 然后对每个面进行底漆，`paint_faces` 允许你在相对于面的坐标中绘制特征（眼睛，鼻子，爪子），这样你就不需要手动计算绝对 UV。
## 示例：动画 GeckoLib 熊
AI 执行以下操作以实现 “制作一个可以行走、奔跑、睡觉和攻击的纹理 GeckoLib 熊”：
```jsonc
// 0. 读取手册，以便模型详细且旋转，而不是盒子
get_guide {}
// 1. 安装 GeckoLib（添加 `geckolib_model` 格式）
install_plugin { "id": "geckolib" }
// 2. 新项目，直接从启动屏幕
new_project { "format": "geckolib_model", "name": "bear",
"texture_width": 64, "texture_height": 64 }
// 3. 布局整个姿势的骨架，一次调用 — 注意旋转的骨骼
add_groups { "groups": [
{ "name": "body", "origin": [0, 12, 0] },
{ "name": "head", "origin": [0, 14, -7], "parent": "body", "rotation": [10, 0, 0] }, // 鼻子向下
{ "name": "leg_fl", "origin": [3, 8, -5], "parent": "body", "rotation": [-6, 0, 0] },
{ "name": "leg_fr", "origin": [-3, 8, -5], "parent": "body", "rotation": [-6, 0, 0] }
// ... 后腿，耳朵，鼻子，尾巴...
] }
// 4. 构建多个立方体（分段肢体，锥度，镜像左右）
add_cubes { "cubes": [
{ "name": "torso", "from": [-5, 8, -7], "to": [5, 16, 7], "parent": "body" },
{ "name": "head", "from": [-3.5, 10, -13], "to": [3.5, 16, -7], "parent": "head" },
{ "name": "muzzle", "from": [-2, 10, -16], "to": [2, 13, -13], "parent": "head", "inflate": -0.5 }
// ...
] }
// 5. 纹理：每个面着色基础层（无间隙），然后相对面特征
create_texture { "name": "bear", "width": 64, "height": 64, "fill": "#6e4a2b" }
detail_cubes { "base": "#6e4a2b", "noise": 0.12, "bottom_dark": 0.3 }
paint_faces { "faces": [
{ "cube": "head", "face": "north", "ops": [
{ "type": "rect", "x": 2, "y": 2, "width": 1, "height": 1, "color": "#0f0a05" }, // 眼睛
{ "type": "ellipse", "x": 3, "y": 4, "width": 2, "height": 2, "color": "#140e08" } // 鼻子
] }
] }
// 6. 动画（批量关键帧，平滑插值）
create_animation { "name": "animation.bear.walk", "loop": "loop", "length": 1.2 }
add_keyframes {
"animation": "animation.bear.walk",
"keyframes": [
{ "bone": "leg_fl", "channel": "rotation", "time": 0.0, "value": [28, 0, 0], "interpolation": "catmullrom" },
{ "bone": "leg_fl", "channel": "rotation", "time": 0.6, "value": [-28, 0, 0], "interpolation": "catmullrom" },
{ "bone": "leg_fl", "channel": "rotation", "time": 1.2, "value": [28, 0, 0], "interpolation": "catmullrom" }
]
}
// 7. 从各个角度查看 + 审计，修复你看到的问题，然后重复 4-7
screenshot_views { "views": ["isometric_right_front", "front", "left", "back"] }
check_model {}
// 8. 保存/导出
save_project { "path": "D:/models/bear.bbmodel" }
export_project { "path": "D:/models/bear.geo.json" }
```
## 故障排除
**Blockbench 显示“服务器已停止”，启动无效果。**
插件需要 `net` 模块。单击 **启动 MCP 服务器** 时，Blockbench 会显示权限对话框 - 选择 **“对此插件始终允许。”** 如果您之前拒绝了，请撤销并重试插件的上下文菜单，或重新启动 Blockbench。
**MCP 工具因“无法在 127.0.0.1:8787 访问 Blockbench”而失败。**
确保 Blockbench 已打开，插件已加载，服务器正在运行（绿色 toast / `curl .../ping` 有效）。确认插件设置中的端口与 `BLOCKBENCH_MCP_PORT` 匹配。
**“未知格式…必须安装匹配的插件。”**
诸如 GeckoLib 的 `geckolib_model` 之类的插件格式需要先 `install_plugin { "id": "geckolib" }`。运行 `list_formats` 以确认 ID 出现。
**控制台 404 关于 `about.md` / 插件商店。**
无害 - Blockbench 尝试获取侧载插件的商店元数据并得到 404。它不会影响桥接。
## 安全
- 桥接仅绑定到 **`127.0.0.1`** - 它无法从您的网络访问。
- `execute_script` 在 Blockbench 内运行 **未沙盒 JavaScript**。仅连接您信任的 MCP 客户端，并尽可能优先使用专用工具而不是 `execute_script`。
## 限制
- **仅限桌面版。** 桥接依赖于 Node 模块（`net`），而 Blockbench 网页应用程序不向插件公开这些模块。
- **单个 Blockbench 窗口。** 桥接与当前活动的项目对话。
- 调用者负责盒子 UV 包装；`add_cube` 返回解析后的面 UV 矩形，以便使其可管理。
## 开发
```bash
npm run dev # tsc --watch
npm run build # 一次编译到 dist/
```
- MCP 工具定义位于 [`src/tools.ts`](src/tools.ts)；HTTP 客户端位于 [`src/client.ts`](src/client.ts)；服务器入口位于 [`src/index.ts`](src/index.ts)。
- 桥接命令处理程序位于 [`plugin/blockbench_mcp.js`](plugin/blockbench_mcp.js) 下的 `commands` 对象 - 在那里添加处理程序，并在 `tools.ts` 中添加匹配的工具以扩展表面。
- 桥接使用的 Blockbench API 在 [官方类型定义](https://github.com/JannisX11/blockbench/tree/master/types) 中有文档记录。
## 许可证
[MIT](LICENSE) © [sosadly](https://github.com/sosadly)
使用 [模型上下文协议](https://modelcontextprotocol.io/) 构建。不属于 Blockbench 或 GeckoLib。
