Minecraft Blockbench MCP

让 AI 在 Blockbench 桌面版和 Web 版中制作 Minecraft 生物模型、贴图与骨骼动画，主要面向 BetterModel / ModelEngine。

0.1.0-alpha.2 · GPL-3.0-only · 开发分支 Alpha

这是三个开源 MCP 的实际代码整合：一个编辑器插件、一个本地 MCP 服务、一个共享执行队列。整合了近 200 个工具，数量和可用性以连接后的 tools/list 为准。

复杂生物可以组合多层骨骼、翅膀、尾巴、下颚、分部贴图和多段动作。骨架模板只是可编辑草模；动画槽也需要继续编写关键帧。游戏内寻路、战斗逻辑和技能触发由服务器插件负责。

安装

需要 Node.js 22+、Blockbench 5.1+，以及支持 Streamable HTTP MCP 和 Bearer 请求头的本地 AI 客户端。Web 版同样需要本机运行 Node 服务。

git clone https://github.com/zkonikishi/Minecraft-Blockbench-MCP.git
cd Minecraft-Blockbench-MCP
npm ci --ignore-scripts
npm run build
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

将生成的随机值作为自己的 token。复制 .env.example 为 .env，填入 token，然后启动：

npm start

1. 在 Blockbench 打开 文件 → 插件 → 从文件加载插件，选择 dist/minecraft_blockbench_mcp.js。发布包中的同名文件也可直接使用。

2. 在 设置 → 常规中找到 Minecraft MCP token，填入与 .env 相同的值。

3. 保持 Minecraft MCP bridge URL 为 ws://127.0.0.1:39800/bridge。

4. 点击 工具 → Connect Minecraft MCP，看到 connected 后再连接 AI 客户端。

5. 升级前先断开连接并卸载旧插件，再加载新文件。不要重复加载同一个插件。

Web 安装同样使用“从文件加载”。Blockbench 不允许通过普通 HTTP URL 安装插件，即使 URL 指向本机。官方 Web 页面连接本机时，按浏览器提示允许该页面的本地网络连接；若浏览器阻止连接，查看开发者日志或使用桌面版。

在 AI 客户端配置中填写以下连接信息。不同客户端的字段名称可能不同，不要把示例 token 当作真实密钥：

{
  "url": "http://127.0.0.1:39800/mcp",
  "headers": { "Authorization": "Bearer YOUR_RANDOM_TOKEN" }
}

服务仅监听本机回环地址。远程云端客户端不能直接访问你电脑的 127.0.0.1。同一服务只连接一个 Blockbench 窗口；多个窗口请使用不同端口和 token。断线或工具配置变更后重新连接，并刷新客户端的工具列表。

制作流程

先让 AI 调用 mc_get_workflow 和 mc_engine_profile，再开始编辑。例如：

为 BetterModel 和 ModelEngine 制作一个朝向 -Z 的翼龙草模。创建独立 Generic 项目，使用 mc_scaffold_creature 生成 dragon 骨架。细化翅膀、尾巴和下颚，排布面 UV、绘制贴图，给 idle 和 walk 写入真实骨骼关键帧。用多角度截图检查轮廓。最后运行 mc_audit_model，修复错误，再用 mc_export_bbmodel 导出内嵌纹理的文件。不要把空动画槽当作完成的动画。

主要操作顺序：

1. mc_create_project → mc_scaffold_creature，或自行创建完整几何。

2. craft_apply_geometry_batch / studio_place_cube 等工具细化。

3. craft_ensure_texture → craft_pack_box_uv → 绘制工具。

4. mc_create_animation_set → anim_add_keyframes / craft_upsert_animation。

5. craft_capture_views → mc_audit_model。

6. mc_export_bbmodel 返回模型 JSON；download: true 请求编辑器下载文件。

工具参数应以 tools/list 返回的 schema 为准。上游说明中的裸工具名称对应本项目的前缀名称。craft_upsert_animation 的 replace: true 会替换整段动画，请先读取已有内容。

引擎适配范围

target: "both" 采用保守交集；它不会同时模拟两个引擎，也不会自动转换所有引擎特性。骨骼预算默认 64 只是提醒阈值。完整差异与依据见 兼容性说明。

Alpha 2 按官方 Wiki 扩展骨骼标签，并增加 mc_modelengine_features，区分已实现、仅供参考和待验收功能。Wiki 没有锁定具体 Dev 构建号，因此不宣称支持所有 Dev 特性；脚本关键帧和服务器 API 仍无专项实现。本轮新增功能经过模拟编辑器与静态测试，尚未补做真实编辑器/游戏内验收。

测试与当前边界

本地 Windows 检查包含类型检查、整合/协议/回归测试，以及 69 项选定上游测试。这些测试覆盖本项目与选定上游范围，不代表每个工具已实机验证。

实际 Web 验证使用官方 Blockbench 5.1.6 源码构建的本地页面：加载插件、认证连接、三个工具家族协作、创建翼龙草模、贴图与 UV、idle 关键帧、PNG 预览、内嵌纹理 .bbmodel 导出均通过。官网 https://web.blockbench.net/ 在测试主机连接失败，因此尚未验证官网 HTTPS 页面的完整连接流程。

桌面版实际运行、BetterModel / ModelEngine 服务器导入、资源包和 Minecraft 客户端效果尚未验收。 静态检查成功不代表游戏内完全兼容。

npm run check
npm run test:upstream
# 连接专用测试编辑器后执行；会新建测试项目：
npm run test:live -- --confirm-disposable

BLOCKBENCH_BUILD_DIR 可指定构建输出目录；BLOCKBENCH_TEST_DIR 可指定测试产物目录。TypeScript 检查针对自有 TypeScript，原始上游通过适配构建及选定测试验证。详细结构见 架构说明。

高级脚本执行、通用 UI 控制与插件管理默认关闭；需要在编辑器设置启用并重新连接。启用后获得的是本机编辑器权限，不是受限沙箱。工具调用串行执行；长操作超时后可能继续运行，应先检查编辑器再决定是否重试。编辑期间避免手动切换项目。

来源与许可证

采用 GPL-3.0-only，保留三个上游的作者和许可信息。原始文件由 upstream-lock.json 锁定 SHA-256；适配修改位于 src/ 和 scripts/，原始快照保持不变。分发插件时请一并提供许可证、第三方通知和对应源代码。

见 THIRD_PARTY_NOTICES.md 和 LICENSE。本项目并非 Blockbench、BetterModel 或 ModelEngine 官方产品。

English: A unified local MCP for Minecraft creature authoring in Blockbench desktop and Web, targeting BetterModel and ModelEngine. It integrates the original SwagRee, Jason J. Gardner and sosadly tool implementations with a serialized runtime, engine profiles, creature scaffolds, static audits and embedded-texture .bbmodel export. Install dependencies, build, start the loopback relay with a random token, load the plugin file, configure the same token in Blockbench and connect your MCP client. Alpha: local official-source Web workflow tested; desktop and Minecraft engine runtime acceptance remain pending.