Ruin's BlockBenchMCP

Ruin's BlockBenchMCP connects an MCP client to Blockbench Desktop 5.1.6. It provides typed model operations, a high-level task interface, native Blockbench controls, and inspection tools for modeling, UV, texture, animation, and export workflows.

The project is intended for local use. The MCP server communicates with the Blockbench plugin over an authenticated loopback WebSocket connection; it does not expose a public network service.

Astra-first concept

Ruin's BlockBenchMCP is designed first for GPT-6 Astra. Astra handles the visual decisions—reference comparison, Minecraft-style interpretation, per-face texture planning, and multi-view judgement—while this MCP provides the deterministic Blockbench operations, checkpoints, and verification needed to apply those decisions safely. The goal is an authoring loop in which Astra can inspect, create, and revise a complete Minecraft asset instead of producing an isolated model or flat image.

The MCP protocol itself is model-agnostic, but the included Minecraft authoring workflow is Astra-first. Other models can connect to the same tools, while their ability to retain the full reference, texture-density, and visual-review procedure may vary.

Related MCP server: BlockBenchMCP

Features

• Model creation and editing for groups, cubes, meshes, bones, and armatures

• UV editing, seams, islands, projection, density, transforms, and selection

• Textures, layers, raster painting, brush settings, presets, and color picking

• Animation keys, events, controllers, IK configuration, and IK baking

• Mesh topology operations, vertex weights, cleanup, merge, split, and knife tools

• Native actions, menus, modes, settings, key bindings, panels, previews, dialogs, and loaders

• Snapshots, plans, one-step Undo boundaries, checkpoints, diagnostics, captures, and exports

• High level workflows through bb_task, with lower level typed commands available when a workflow needs precise control

• Extension API for Blockbench plugins to register typed MCP operations

The plugin also contains compatibility adapters for supported Blockbench ecosystem extensions. Adapters are activated when their provider is installed and report their availability through bb_capabilities.

Requirements

• Blockbench Desktop 5.1.6

• Node.js 22 or newer

• An MCP client that can start a local stdio server

Blockbench version compatibility is checked at runtime. This repository targets the desktop build; web and mobile builds are outside the supported target.

Installation

Clone or download the repository, then install dependencies and create a local connection configuration:

git clone https://github.com/Ru1n-dev/ruins-blockbench-mcp.git
cd ruins-blockbench-mcp
npm ci
npm run setup

npm run setup creates an ignored .runtime directory, generates a random local token, builds the server and plugin, and writes client configuration examples.

1. In Blockbench, open File > Plugins > Load Plugin from File and choose dist/ruins_blockbench_mcp.js.

2. Add .runtime/mcp-config.json to the MCP client. .runtime/codex-config.toml is provided for clients that use TOML configuration.

3. Reconnect the MCP client and call bb_status. The Blockbench panel Ruin's MCP shows the connection state and recent requests.

The generated configuration uses absolute paths. Run npm run setup again after moving the checkout. Do not commit .runtime, artifacts, or dist; they are generated locally and ignored by Git.

The server is intended for a local MCP client and a local Blockbench instance. The generated token authenticates the loopback bridge; keep .runtime and generated plugin files private to the checkout that created them.

Recommended workflow

For an edit, first call bb_status and bb_projects, then obtain a fresh bb_snapshot. Use bb_plan_edit or the planning phase of bb_task to inspect changes before applying them. Apply the returned plan once, then verify with bb_diagnose, bb_capture, bb_animation_frames, or bb_export as appropriate. Do not treat a successful file write or a single attractive camera angle as proof that the asset is ready for the game.

The plan boundary checks the active project, format, revision, selection and protection rules. Edits are grouped into a native Undo entry where Blockbench provides that boundary. Requests that involve a native dialog or file picker use bb_editor_state, bb_dialog, bb_file_requests, and bb_file_reply so the MCP client can provide the required values or files explicitly.

Tool groups

The server advertises its complete JSON Schemas to the MCP client. The main entry points are:

Use bb_capabilities to discover the actions, codecs, formats, node types, panels, previews, settings, loaders, plugins, and registered extensions available in the current Blockbench session. Native registration discovery does not imply that a provider-specific operation is safe to invoke; unsupported boundaries return a structured error or require an extension adapter.

Minecraft authoring Skill

The repository includes skill/blockbench-minecraft-authoring, a Codex Skill for creating Minecraft-oriented models, UVs, pixel textures, animations, and exports through this MCP. It treats geometry, UVs, texture, animation, and target format as one asset contract and uses the typed plan → apply → verify workflow.

Astra-first Minecraft authoring

The included Skill is primarily authored and validated for GPT-6 Astra. For every Minecraft model, UV, or texture task it creates a reference decision before editing. Reference use is the default, including observation-only comparison when no exact matching asset exists. Each plan records the exact file count, purpose, covered parts/faces/maps, expected decision, and fallback. Skipping references requires an explicit unrelated custom-art reason. For a finished high-density asset, the default four slots cover family/style and face roles, material structure, light/value/baked-shadow treatment, and pixel/detail-density/edge-wear/tiling. Relevant companion maps such as overlays, eyes, emissive, animated, connected/tiling, tint, transparency, or PBR add their own slots.

A reference can be used in three modes: direct assignment, adapted source, or observation-only. Direct assignment is an exceptional exact-compatibility case; normally the reference guides a whole-model texture pass. The Skill records the mode and provenance, and direct use still requires global base, smooth connected value transitions, face-detail, and 3D integration passes. References can provide material identity, light/value hierarchy, baked shading, and surface cues; filenames never determine resource-pack wiring. The call-plan template is in reference-plan.md; detailed pixel and grime/weathering rules are in texture-quality.md.

For high-quality authoring, explicit UV unwrap/mapping is mandatory before painting. Finished assets start with a high-density initial texture pass rather than a base-only draft. Every visible texture-bearing face receives purposeful material variation, macro/meso/micro detail where its UV area supports it, and smooth connected form shading. The workflow has no separate highlight pass; form is communicated through the local value ramp, material structure, and near-colour texture noise. Per-face UV regions are the default so material, brightness, shadows, wear, and damage can be authored independently; shared or mirrored UVs require named faces and a recorded reason. Per-part geometry can use volumetric, rotated-cuboid, or card/plane/billboard representation when the target and view justify it. A final material-aware grime/weathering pass may add controlled inner-to-outer darkening, recess/contact grime, dust, streaks, or handling wear after continuity checks. surface_variation_profile and texture_coverage_matrix make whole-model coverage auditable. Separate islands are kept visually unified through a shared palette/value chart, consistent texel density and orientation, controlled edge padding, cross-face motif checks, and whole-model 3D review.

The helper indexes metadata rather than bundling Mojang/Microsoft image bytes. It supports the pinned Mojang Bedrock Samples tree and a local exact-version Java asset tree, including block, item, entity, attachable, animation, Texture Set, and catalog resources. Fetch only the files needed for a review:

node skill/blockbench-minecraft-authoring/scripts/minecraft_texture_corpus.mjs index --ref main --out .cache/bedrock-textures.json
node skill/blockbench-minecraft-authoring/scripts/minecraft_texture_corpus.mjs query --index .cache/bedrock-textures.json --category entity --match zombie --limit 20
node skill/blockbench-minecraft-authoring/scripts/minecraft_texture_corpus.mjs fetch --index .cache/bedrock-textures.json --match zombie --out .cache/reference-images/zombie --limit 12

For Java, index the extracted assets belonging to the exact client version with index --root <assets-or-checkout>. Keep downloaded references in an ignored temporary directory and retain _reference-manifest.json; do not redistribute the vanilla image corpus.

Multi-view review

The Skill requires a named review of the applicable front, back, left, right, top, bottom, and three-quarter/isometric views. It adds asset-specific checks for display slots, 3×3 block tiling, transparent faces, entity poses, animated extremes, contact points, card/plane alpha boundaries, and other placement variants. Use the detailed gate in multiview-review.md, then repeat affected views after a fix. reference-and-multiview.md remains only as a compatibility router for older links.

Extension API

An optional Blockbench plugin can register a typed operation with the global API exposed by this plugin. See examples/ruins_mcp_example.js and docs/extension-api.md.

The current API is available as globalThis.RuinBlockBenchMCP. globalThis.PerfectBlockbenchMCP remains as a compatibility alias for extensions written against earlier development builds. Registration IDs should use a provider namespace such as my_plugin:operation.

Development

npm ci
npm run check
npm run build
npm test

npm run build writes dist/server.mjs and dist/ruins_blockbench_mcp.js. npm test runs the TypeScript check and a clean production build. Live Blockbench interaction requires a desktop 5.1.6 instance with the generated plugin loaded.

See docs/architecture.md for the public runtime model and docs/tool-reference.md for command conventions.

Troubleshooting

• If the panel does not connect, confirm that Blockbench loaded the generated dist/ruins_blockbench_mcp.js, the MCP client is using .runtime/mcp-config.json, and both sides came from the same checkout and npm run setup run.

• If a request is rejected because the project changed, obtain a new bb_snapshot and create a new plan. Do not blindly resend a mutating request after a timeout.

• If an export opens but does not work in-game, check the target edition/version, codec, resource-pack paths, UVs, filtering, alpha/culling, and runtime logs separately. MCP export success is not in-game compatibility proof.

Scope and limitations

This repository targets the APIs exposed by Blockbench Desktop 5.1.6. Native actions and third-party extensions can impose their own format, selection, dialog, timing, or external-file requirements. The server reports those conditions and does not silently emulate missing provider behavior. Export success confirms that a file was produced; it does not validate a target game's runtime behavior.

License

This repository is proprietary and distributed under an All Rights Reserved notice. Private viewing and evaluation of an unmodified copy are permitted; copying, modifying, redistributing, public hosting, commercial use, or integration into another product requires prior written permission from Ru1n-dev. See LICENSE. Third-party dependencies remain subject to their own licenses.