BlockBenchMCP

Minecraft-oriented Model Context Protocol as a pure Blockbench desktop plugin (≥ 5.1.0).

Install the plugin → it hosts loopback HTTP MCP → point Cursor at the URL. No separate Node adapter. Closing Blockbench stops MCP.

Intent-level tools (scaffold_biped, check_model, …) — not a thin UI mirror.

Install

Artifact (recommended): download blockbench_mcp.js from GitHub Releases.

From source:

git clone https://github.com/SwagRee/BlockBenchMCP.git
cd BlockBenchMCP
npm install && npm run build

Output: packages/plugin/dist/blockbench_mcp.js.

1. Blockbench: File → Plugins → Load Plugin from File

2. Allow network / net when prompted

3. Listens on http://127.0.0.1:39741/mcp (or Tools → Start / Stop MCP Server)

4. Settings: port + Bearer (default dev-local-secret)

Related MCP server: Minecraft Dev MCP

Cursor

{
  "url": "http://127.0.0.1:39741/mcp",
  "headers": { "Authorization": "Bearer dev-local-secret" }
}

Open Blockbench first, enable MCP, call health.

Architecture

AI client  --HTTP MCP-->  packages/plugin (inside Blockbench)

Security: loopback only; Bearer required; file export needs propose_scoped_directory confirmation.

Scope (v1)

Non-goals: trigger_action / emulate_clicks / risky_eval, full paint UI, Hytale, etc.

Main tools

Mutations return explicit success/failure; unknown params hard-error. Prefer check_model over vision spam.

The safe edit loop is complete: inspect exact element geometry and per-face UVs with get_elements, make bounded changes with update_elements / set_face_uv, then read back and review. save_project writes a real .bbmodel; export_model compiles through the active format codec. Both require an approved scoped directory and explicit overwrite.

Iterative modeling no longer requires recomputing every absolute coordinate: transform_elements applies relative translation, scaling, and pivoted rotation; array_cubes builds repeated geometry while explicitly sharing or regenerating UVs. measure_model reports overall or subtree bounds, center, size, cube count, and volume, while audit_symmetry reports left/right coordinate error. Dimension changes can choose uv_policy: preserve|auto; re-check the UV layout before painting.

Advanced iteration adds rotation- and parent-hierarchy-aware world bounds, radial arrays, deep hierarchy duplication, island-level UV transforms, and explicit intentional-overlap declarations. ensure_material_set creates channel sheets and audit_material_set validates base/emissive/normal/specular channel consistency without pretending Blockbench formats all export the same material semantics. analyze_view_silhouette turns multi-view captures into numeric bounds and coverage, while animation keys can be inspected, retimed, scaled, or mirrored.

Workflow

1. get_guide(modeling)

2. create_project

3. Entities: scaffold_biped / blocks: apply_geometry_batch

4. Fix errors, then texture

5. pack_box_uv → get_uv_layout (zero out-of-bounds; review overlaps/density) → get_uv_map → paint → get_texture / capture_views

6. capture_views only if needed

For a real Blockbench integration gate, open a disposable project with the plugin loaded and run npm run test:e2e. The command requires an explicit disposable confirmation and performs a live create → geometry → UV → paint → audit → multi-view sequence; it is intentionally separate from the deterministic unit suite.

capture_views and get_texture return native MCP image content so compatible clients can render previews directly. For crisp pixel work, paint_pixel_batch accepts multiple face-local paths with square or circle brushes, clips them to their UV faces by default, and commits the whole batch as one undo step.

Each orthographic capture also reports visible_face (north, south, etc.). This names the model face looking toward the camera; isometric captures report null. Use it to place focal details deliberately instead of guessing front-face orientation from a prior project.

get_uv_layout provides machine-readable islands, overlap pairs, texel density, flips, rotation, and bounds. get_uv_map returns a labeled atlas preview. Face-local painting honors rotated/flipped UVs; subset packing preserves existing islands by default, and resize_texture can scale the bitmap and all UVs together.

For precision pixel art, paint_face_grid writes an exact palette-indexed grid whose dimensions must match the face; palette values support CSS RGBA and null for true transparent erase. get_face_grid reads the exact RGBA texels back in the same face-local orientation. Surgical editing, tolerant color replacement, face copy/mirror/rotation, palette statistics, and checkerboard pixel zooms are also available. PNG import/export is confined to a directory explicitly approved with propose_scoped_directory.

Long-running agents can use get_texture_revision and pass its token as expected_revision to destructive texture operations; stale edits fail instead of overwriting newer work. Bounded flood fill and lossless face/region transforms cover enclosed areas and symmetry fixes. audit_texture_quality turns pixel-art rules into per-face findings for palette excess, weak base coverage, isolated pixels, flat fills, and optional transparent-glass edge/center alpha structure.

Check uv_mode on health / get_project_summary: java_block → face; Bedrock → preserve the project's box or per-face UV mode.

Bedrock workflow

• Create a separate entity tab without GeckoLib: create_project({format:"bedrock", name:"Costume", geometry_name:"costume", uv_mode:"face", texture_width:256, texture_height:256}).

• Use bedrock_old only when legacy export is required. UV modes unsupported by the installed format are rejected before creating a project.

• Existing tabs are preserved. A missing native creation API fails rather than opening a wizard that could leave the reference active.

• update_elements immediately refreshes transforms and visibility. Bone undo data is separate from cube undo data.

• transform_elements transforms an entire selected subtree once, even if children are also selected. Coordinates are in the selected root's parent space. Rotation is composed around the requested pivot; non-uniform scale of rotated/inflated geometry is rejected because cuboids cannot represent shear.

• capture_views uses an offscreen orthographic camera fitted to visible geometry, including bone rotations and inflation. It does not translate the model or change the user's camera.

• Saving still requires propose_scoped_directory confirmation, desktop module permission, and overwrite:true for existing files. save_project writes editable .bbmodel; export_model uses the current Bedrock codec for geometry JSON. They are different deliverables.

Validation: npm test includes shared contracts and mocked desktop-host regressions; npm run typecheck and npm run build validate the plugin. The destructive live smoke suite is not part of npm test: run it only with a disposable project. Reload packages/plugin/dist/blockbench_mcp.js in Blockbench to activate a newly built version; an already running MCP server continues using its loaded code until reload.

Agent skill

Pixel-art modeling playbook: skills/blockbench-pixel-art/openai.

License

MIT