Minecraft Blockbench MCP

English | 简体中文

Current release: 1.1.0. Every automated gate passes on a 10-job matrix (ubuntu / windows / macos × Node 22 and 24, plus ubuntu × Node 26, plus the vendored Jason upstream suite on all three platforms): type checking, build, 85 project regression tests, 117 SwagRee/sosadly tests, 1035 vendored Jason tests, a clean production dependency audit and staged-release verification. Editor, engine, upgrade-rollback and stability acceptance all pass: connection, automatic reconnect, visual capture, undo recovery and the full authoring workflow against Blockbench 5.2.1 Web and the installed Blockbench 5.1.6 Desktop; the exported models load and generate resource packs on Paper with ModelEngine R4.2.0, CraftEngine 26.9.2-SNAPSHOT and BetterModel 3.5.0; upgrading from the released v0.1.0-alpha.10 and rolling back both preserve the open project and the token; and a 15-minute soak with 9 relay restarts showed no failures, no handle leak and no memory growth. Graphical client rendering is not part of the acceptance scope and is listed as a known limitation — see release gates.

Let AI author Minecraft models, textures and skeletal animation in Blockbench Desktop and Web, and export to BetterModel, ModelEngine and CraftEngine.

One Blockbench plugin, one local MCP service, one shared serial execution queue. The current Alpha branch exposes 264 default Web editor tools (271 with Advanced enabled) plus 2 offline YSM tools, so a default Web client's tools/list sees 266. Desktop exposes 277 (284 with Advanced, 279/286 via tools/list) and adds file-related capabilities. Ten of these are the GeckoLib family added in 1.1.0. Actual availability is whatever tools/list returns after connecting.

What is in this release

• Upstream sync. Jason blockbench-mcp-plugin v1.9.3, sosadly blockbench-mcp and OpenYSM/YSMParser v0.3.6 are pinned at their current commits; SwagRee is already at its latest. The vendored trees are byte-identical to those commits.

• Verifiable packaging. A staged release now carries the 98-file dependency license inventory, SHA256SUMS, the GPL text and the third-party notices, and the verification gate fails if any of them is missing.

• Reproducible upstream pin. upstream-lock.json records the upstream sources' own SHA-256 over 428 files, so the snapshot can be re-checked against upstream.

• Editor, engine, upgrade and stability acceptance. Connection, automatic reconnect, visual capture, undo recovery and the full authoring workflow pass against Blockbench 5.2.1 Web and the installed Blockbench 5.1.6 Desktop; the exported models load and generate resource packs on Paper with ModelEngine R4.2.0, CraftEngine 26.9.2-SNAPSHOT and BetterModel 3.5.0; upgrading from the released v0.1.0-alpha.10 and rolling back both preserve the open project and the token; and a 15-minute soak with 9 relay restarts showed no failures, no handle leak and no memory growth.

• Single-sourced version. The plugin, the relay and mc_status all derive their version from package.json.

• Offline YSM recovery. mc_ysm_inspect / mc_ysm_recover and a CLI recover .bbmodel, textures and bone animation from .ysm containers without Minecraft, the mod, or an editor.

• Animation and visual review. Read-only animation diagnostics, dry-run bone chain variants, playable frame atlases, and six shared visual tools (multi-view, framing, texture/UV, animation frames, before/after comparison).

Related MCP server: Blockbench MCP

What you can do

Skeleton templates are a starting point; animation slots still need real keyframes. Pathfinding, combat AI and skill logic remain the job of the game or server plugin.

Engine support scope

Quick start

Requires Node.js 22+, Blockbench 5.1+, and an AI client that supports Streamable HTTP MCP with Bearer headers. The Web editor also needs this MCP service running locally.

1. Install and start the service

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'))"

Put the generated value into MINECRAFT_BLOCKBENCH_TOKEN in .env, then start:

npm.cmd start

You can also use the run ZIP from the releases page: unpack it, install dependencies, configure .env and start — it already contains a compiled dist/minecraft_blockbench_mcp.js. Downloading the plugin JS alone does not replace the local service.

The release page lists a SHA-256 digest for every uploaded asset, so a download can be checked without a separate checksum file. Inside the ZIP, manifest.json records a SHA-256 for all 158 packaged files and dist/SHA256SUMS covers the plugin bundle; after installing dependencies, node scripts/verify-release.mjs <unpacked-directory> re-checks the whole manifest.

2. Connect Blockbench

1. Open File → Plugins → Load Plugin from File and select dist/minecraft_blockbench_mcp.js.

2. Find Minecraft MCP token in the settings and enter the same value as the server.

3. Keep the bridge URL at ws://127.0.0.1:39800/bridge.

4. Click Tools → Connect Minecraft MCP.

The Web edition uses the same file-loading path. Blockbench's plugin URL installer does not accept plain HTTP; a file-loaded plugin is also not persisted across page reloads. See persistent loading and reconnect for a local Web host.

When upgrading, update both the plugin and the relay sources and restart the relay; an existing token keeps working. Reconnect and refresh the client's tool list after changing tool settings.

3. Configure your AI client

These are the connection details; field names differ between clients:

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

Call mc_status after connecting to check the version, the current project and the tool count. The service listens on the loopback interface only, so a cloud client cannot reach 127.0.0.1 on your machine. One relay serves one editor window.

4. Verify it really works

Starting the MCP service, the client discovering tools, and Blockbench connecting are three independent steps. Treat a successful mc_status that returns editor state as the signal; seeing a tool list alone does not mean you can edit a model.

Example requests

Once connected you can describe a goal directly, for example:

• "Build a quadruped for BetterModel with jaw and tail bones and idle / walk animations, check it, then export."

• "Check whether the current model conforms to ModelEngine, list the bone, texture and animation problems, fix them, and export both engine variants."

• "Export the current Java Block model as a CraftEngine static furniture content pack and generate the resource-pack merge plan."

These are authoring examples; results still need previewing and engine verification. AI does not get complete motion or combat behaviour from a skeleton template alone.

Three authoring workflows

BetterModel / ModelEngine creatures

Call mc_get_workflow and mc_engine_profile first, then create or import a project:

1. mc_create_project / mc_import_bbmodel → modelling and texturing.

2. Author bone animation and check the motion with the preview tools.

3. mc_audit_model → fix the compatibility problems for the target engine.

4. mc_export_bbmodel / mc_export_engine_variants → export.

target: "both" applies conservative shared rules; it does not mean every engine feature converts. ModelEngine's animation.override must be a boolean — validation reports an error instead of writing a value for you. See compatibility and workflow tools.

CraftEngine items and furniture

Call mc_craftengine_profile to inspect the scope, then mc_craftengine_export to generate the file manifest of a CE content pack:

• Static models use a Java Block/Item project, per-face UV and an embedded PNG, and CE blueprints generate the resource-pack model.

• Dynamic furniture references an installed BetterModel / ModelEngine model; the corresponding engine still owns the animation.

• mc_craftengine_pack_plan produces a merge plan that preserves existing entries and follows CE's normal pack distribution.

The release ships a content-pack installer that pre-checks and refuses to overwrite an existing directory. The MCP never uploads a resource pack or modifies server credentials. See CraftEngine for full parameters, installation and reloading.

Importing existing models

• mc_import_bbmodel: pass parsed model JSON and create a project through the native codec; embedded PNGs are required. Parameters and limits

• mc_import_cem: pass JEM JSON to restore native geometry and UV, strip texture paths and reject external JPM references; CEM animation expressions are not converted. Parameters and limits

Tool parameters are defined by the schemas returned from tools/list. Avoid switching projects while editing; after a long operation times out, inspect the editor state before deciding whether to retry.

Verification status

Automated, reproducible today:

Historic acceptance records, listed for context:

These records do not cover every tool, every model or future engine versions. The engine flows above were verified server-side — model import and resource-pack generation on an isolated Paper server — and not by eye in a running client. The graphical Minecraft client result and the actual Beta upload have not been accepted. See runtime acceptance and CE acceptance scope.

Development and tool sources

npm.cmd run check
npm.cmd run test:upstream
# The following create a new project in a dedicated test editor:
npm.cmd run test:live -- --confirm-disposable
node scripts/live-workflow.mjs --confirm-disposable
# Web editor acceptance in a headless browser (one-off: npm i playwright-core):
$env:MINECRAFT_BLOCKBENCH_TOKEN = '<your relay token>'
npm.cmd run test:web

BLOCKBENCH_BUILD_DIR and BLOCKBENCH_TEST_DIR set the build and test output directories. Original upstream snapshots are pinned by upstream-lock.json; the adaptation code lives in src/ and scripts/. See architecture.

Advanced script execution, general UI control and plugin administration are off by default and must be enabled in the local editor settings. Enabling them grants local editor privileges, not a restricted sandbox.

Roadmap

Offline YSM recovery shipped in this line; Armourer's Workshop (AM/AW) is still not implemented. Next: broader YSM format and sample coverage, animation controllers and complex material mapping. See YSM scope and development roadmap.

License

GPL-3.0-only. The four upstream projects' authors and licenses are preserved; when redistributing, also provide the corresponding source, the licenses and the third-party notices. See LICENSE.

This project is not an official Blockbench, BetterModel, ModelEngine or CraftEngine product.