Minecraft Blockbench MCP

让 AI 在 Blockbench 桌面版与 Web 版中制作 Minecraft 模型、贴图和骨骼动画，并对接 BetterModel、ModelEngine、CraftEngine。

当前发布：Alpha 10 · 开发分支 Alpha · 中文文档 / English overview below

当前进入发布收尾，冻结新功能。RC/正式版以实机及安装包验收为准，不以工具数量或单元测试代替。

下载发布包 · Alpha 10 发布页 · CraftEngine 接入 · 开发路线

一个 Blockbench 插件、一个本地 MCP 服务，共用串行执行队列。当前 Alpha 10 提供 235 个默认 Web 编辑器工具 + 2 个离线 YSM 工具；桌面版另有文件相关能力，实际可用工具以连接后的 tools/list 为准。

Alpha 10：YSM 离线恢复

Alpha 分支新增 动画质量流程：只读动画诊断、带 dry-run 的多骨骼链/多头变体、可播放和拖动的连续帧图册。原动作保留，不把自动复制动作视为专业动画设计或游戏内验收。

Alpha 开发分支：全局视觉工具

新增 6 个公共视觉工具，覆盖多视角/线框、局部特写与骨骼叠加、贴图/UV、动画逐帧和前后对比，不限 YSM 或任何模型引擎。scripts/review-model.mjs 输出通用 HTML 图册；原 YSM 命令保留兼容。见 视觉工作流。这些是 Alpha 分支更新，尚未包含在既有 Alpha 10 发布包中；编辑器实机验收另行记录，图片采集不代表视觉或游戏验收通过。

新增 mc_ysm_inspect / mc_ysm_recover 和离线 CLI：从 .ysm 恢复 .bbmodel、贴图与骨骼动画，保留原始资源并输出差异报告。无需启动 Minecraft、YSM Mod 或编辑器。已验证 V1、V2、BOM V3 各一个样本；不承诺无损或全部版本覆盖。见 YSM 使用说明。

Related MCP server: BlockbenchMCP

Alpha 9 更新

同步 Jason v1.7.0 与 sosadly 2026-09-12 快照，SwagRee 快照保持不变。

• 新增 studio_get_display_transform、studio_set_display_transform、studio_enter_display_mode，用于物品展示设置。

• 新增 anim_add_wing，生成翅膀骨骼与翼膜；同时更新上游骨架、动作与模型检查能力。

• 修复 studio 关键帧数值、非均匀缩放与零值编辑，以及贴图渲染设置保留。

• 修复异步 codec 导出；新增桌面专用 anim_export_model。

• 脚本执行继续受本地 Advanced 开关控制；依赖上游 Copilot 面板的三个交互工具不注册。

详见 Alpha 9 更新与验证。

可以做什么

骨架模板是制作起点，动画槽需要写入真实关键帧。寻路、战斗 AI 和技能逻辑仍由游戏或服务器插件负责。

引擎支持范围

快速开始

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

1. 安装并启动服务

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

将生成的随机值填入 .env 的 MINECRAFT_BLOCKBENCH_TOKEN，然后启动：

npm.cmd start

也可使用发布页的运行 ZIP：解压、安装依赖并配置 .env 后启动，包内已有编译好的 dist/minecraft_blockbench_mcp.js。单独下载插件 JS 不能代替本地服务。

2. 连接 Blockbench

1. 打开 文件 → 插件 → 从文件加载插件，选择 dist/minecraft_blockbench_mcp.js。

2. 在设置中找到 Minecraft MCP token，填入与服务端相同的值。

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

4. 点击 工具 → Connect Minecraft MCP。

Web 版使用相同的文件加载方式。Blockbench 的插件 URL 安装器不接受普通 HTTP 地址；文件安装的插件也不会自动跨页面重载持久保存。本地 Web 主机可参考持久加载与重连说明。

升级时更新插件和 relay 源码，并重启 relay；已有 token 可继续使用。修改工具设置后重新连接并刷新客户端工具列表。

3. 配置 AI 客户端

以下是连接信息，不同客户端的配置字段可能不同：

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

连接后调用 mc_status 检查版本、当前工程和工具数量。服务仅监听本机回环地址，云端客户端无法直接访问你电脑的 127.0.0.1。一个 relay 同时连接一个编辑器窗口。

4. 确认真正连通

MCP 服务启动、客户端发现工具、Blockbench 编辑器连接是三个独立环节。以 mc_status 成功返回编辑器状态为准，单纯看到工具列表不代表可以操作模型。

示例请求

连接后可以直接对 AI 描述目标，例如：

• “制作一个用于 BetterModel 的四足生物，包含下颚、尾巴骨骼和 idle / walk 动画，检查后导出。”

• “检查当前模型是否符合 ModelEngine，列出骨骼、贴图和动画问题，修复后分别导出两个引擎版本。”

• “把当前 Java Block 模型导出为 CraftEngine 静态家具内容包，并生成资源包合并方案。”

这些是制作任务示例，最终结果仍需预览与引擎验证；AI 不会仅凭骨架模板自动获得完整动作或战斗行为。

三条制作流程

BetterModel / ModelEngine 生物

先调用 mc_get_workflow、mc_engine_profile，再创建或导入工程：

1. mc_create_project / mc_import_bbmodel → 建模与贴图。

2. 编写骨骼动画，使用预览工具检查动作。

3. mc_audit_model → 修复目标引擎的兼容性问题。

4. mc_export_bbmodel / mc_export_engine_variants → 导出。

target: "both" 使用保守的共同规则，不表示所有引擎特性都能互转。ModelEngine 的 animation.override 必须是布尔值；校验会报告错误，不会擅自补写。详见兼容性说明与工作流工具。

CraftEngine 物品与家具

调用 mc_craftengine_profile 查看范围，再用 mc_craftengine_export 生成 CE 内容包文件清单：

• 静态模型使用 Java Block/Item 工程、逐面 UV 和内嵌 PNG，由 CE 蓝图功能生成资源包模型。

• 动态家具引用已安装的 BetterModel / ModelEngine 模型，动画仍由对应引擎负责。

• mc_craftengine_pack_plan 生成保留已有条目的合并方案，沿用 CE 的发包流程。

发布包附带内容包安装脚本，支持预检并拒绝覆盖已有目录。MCP 不会自动上传资源包或修改服务器凭据。完整参数、安装与重载方法见 CraftEngine 使用说明。

已有模型导入

• mc_import_bbmodel：传入解析后的模型 JSON，通过原生 codec 新建工程，要求内嵌 PNG。参数与限制

• mc_import_cem：传入 JEM JSON，恢复原生几何与 UV，移除纹理路径并拒绝外部 JPM 引用；不转换 CEM 动画表达式。参数与限制

工具参数以 tools/list 返回的 schema 为准。编辑期间避免切换工程；长操作超时后应先检查编辑器状态再决定是否重试。

验证情况

Alpha 9 已通过 51 项整合测试、48 项 sosadly 翅膀/桥接测试及原有上游测试；Web 连通和工具列表另行实测。以下为 Alpha 8 及注明的历史测试记录，不代表你当前电脑上的连接状态。

这些记录不代表每个工具、每个模型或未来引擎版本均已验收。图形 Minecraft 客户端效果、Alpha 8 的实际 Beta 上传，以及 CE 动态家具的外部引擎渲染尚未完成本次验收。 详见引擎运行记录与CE 验收范围。

开发与工具来源

npm.cmd run check
npm.cmd run test:upstream
# 以下操作会在专用测试编辑器中新建工程：
npm.cmd run test:live -- --confirm-disposable
node scripts/live-workflow.mjs --confirm-disposable

BLOCKBENCH_BUILD_DIR 与 BLOCKBENCH_TEST_DIR 可分别指定构建及测试产物目录。原始上游快照由 upstream-lock.json 锁定，适配代码位于 src/ 和 scripts/。详见架构说明。

高级脚本执行、通用 UI 控制与插件管理默认关闭，需在本地编辑器设置中启用。启用后获得的是本机编辑器权限，不是受限沙箱。

后续计划

YSM 离线恢复已在 Alpha 10 实现，时装工坊（AM/AW）仍未实现。 后续完善 YSM 更多格式与样本覆盖、动画控制器和复杂材质映射。见 YSM 范围与开发路线。

许可证

GPL-3.0-only。保留三个上游的作者与许可信息，分发时请同时提供对应源码、许可证与第三方通知。详见 LICENSE。

本项目并非 Blockbench、BetterModel、ModelEngine 或 CraftEngine 官方产品。

English: A local MCP for Minecraft modeling, texturing and animation in Blockbench Desktop and Web. Supports BetterModel / ModelEngine creature workflows, CraftEngine item blueprints and furniture references, and native bbmodel / CEM JSON import. Alpha 8 has 211 verified default Web tools and 47 passing regression tests. Engine and resource-pack acceptance is documented separately from graphical client validation. Alpha 10 adds offline YSM recovery (two relay tools and a CLI), tested on representative V1/V2/BOM V3 samples; Armourer's Workshop remains planned.