v1.9.0.1 — Detached parts

Detached parts

validate_model now finds parts that float free of the model: a leg hovering 1 unit under the torso, a paw sitting beside its leg. Before, only intersections were checked, so these models passed.

• A cube or mesh counts as attached when its world box touches or overlaps a part in its own, parent, child or sibling bone. Everything outside the main body is listed with its bone, the nearest neighbour and the [x, y, z] gap in units.
• Works at the rest pose and at animation times (animation + times), in the same pass as the intersection check.
• On by default. detached: false turns it off; tolerance (default 0.01) is also the largest gap that still counts as touching.
• No more computing gaps by hand from query_geometry boxes.

New test: scripts/verify-detached.mjs.

v1.9.0 — Headless mode

Headless mode

Blockbench no longer has to be open. Add BB_HEADLESS=1 to the server's env:

"env": { "BB_BRIDGE_PORT": "8188", "BB_HEADLESS": "1" }

When a tool needs Blockbench and none is connected, the server starts it with its window hidden, waits for the plugin to connect (about 5 seconds), and then runs the tool. Every tool works while the window is hidden; screenshots and renders draw offscreen.

• New tool blockbench_window (status, show, hide): show the window when you want to look at the model, hide it again. Works with or without headless mode.
• A Blockbench that is already running is used as it is; its window is not hidden and it is never started twice.
• BB_EXECUTABLE points to Blockbench if it is not in the default install folder. BB_LAUNCH_TIMEOUT_MS (default 90000) limits how long the server waits for the plugin.
• Clear errors when the executable is missing, when Blockbench starts but the plugin never connects, and when Blockbench runs but its plugin listens on another port.
• Windows only for hiding the window. On macOS and Linux the server still starts Blockbench, but the window shows. On a Linux server without a display, point BB_EXECUTABLE at a script that runs Blockbench under xvfb-run.

See Headless mode.

Also in this release

• Failed batches roll back completely. When add_cubes, add_groups, add_meshes, add_planes, add_locators, add_bounding_boxes, add_ik_controllers, duplicate_elements or mirror_elements fails partway, nothing it created is left behind. Before, the new nodes survived and fell out of their groups to the root.
• parent names match groups only, so a floor cube in a floor group no longer makes the name ambiguous.
• paint_texture: a rect or ellipse with only thickness draws an outline.
• pixel_density goes up to 512 (32 px per unit). Out-of-range values are an error instead of being clamped to 128.
• Painting an empty group names the groups that do hold cubes or meshes again, with child counts.
• Smaller source files. The 1500-line tool file, the painting code and the outliner edits are split into modules. Tools behave the same and their schemas are unchanged.

Tested on Windows with Blockbench 5.2.2:

• verify-headless 10/10: launch, hidden window, screenshot while hidden, show/hide, two concurrent calls starting Blockbench once, wrong executable, launch timeout, plugin on another port.
• The window is visible for at most one 50 ms sample during launch.
• All other test scripts pass, including the new verify-batch-fixes.

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.

Updating

1. Overwrite both files with the new ones.
2. Restart Blockbench.
3. Restart Claude Desktop or your Claude Code session.

v1.8.0 — Tools from other plugins

Tools from other plugins

Other Blockbench plugins can now give Claude new tools. One call adds a tool and it shows up in Claude's tool list right away:

const tool = BlockbenchMCP.registerTool({
  name: 'model_report',
  description: 'Summarise the open model: bones, cube counts, textures, animations.',
  inputSchema: { type: 'object', properties: { bone: { type: 'string' } } },
}, (args) => ({ project: Project.name /* ... */ }));

tool.delete(); // removes it again

• The tool also appears on relay instances, and disappears on delete() or when Blockbench closes.
• Listen for the blockbench_mcp_ready event to register again after the bridge plugin reloads.
• The server does not check arguments against inputSchema; validate them in the handler.

See Adding tools from another plugin.

Also in this release

• Shorter errors. When a tool handler throws, Claude gets only the message, without the plugin bundle's stack frames (266 → 57 characters for a typical error). The Blockbench console still logs the full error.
• Java force_translucent. create_texture and import_texture take force_translucent: true for Java block/item models. The exported JSON writes the texture as {"sprite": "...", "force_translucent": true}. Needs Blockbench 5.2.2. On older versions you get a clear error, and nothing is changed.

Tested on Blockbench 5.2.2:

• verify-plugin-api 12/12, smoke and e2e tests pass.
• A tool registered from Blockbench was listed, called and removed in a live Claude Code session.
• force_translucent was exported and reopened from a Java block model, and the flag was kept.
• Blockbench 5.2.2 fixes that reach our tools were checked with real models:
  • IK bake on pre-rotated bones, and undo/redo of the bake
  • Vertex weights kept by merge_meshes
  • glTF UVs on multi-texture, non-power-of-2 models
  • FBX export of a mesh with a stray vertex

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.

Updating

1. Overwrite both files with the new ones.
2. Restart Blockbench.

v1.7.1 — Pixel-art parameter descriptions

Pixel-art parameter descriptions

pixel_art actions render and export_sheet share four parameters: animation, pose, directions and mirror_directions. In 1.7.0 only the render descriptions reached Claude, so for sprite sheets the "omit animation for a static sprite" hint was missing. Each parameter now has one description that covers both actions. Behaviour is unchanged.

Grouped tools now refuse to start if two actions describe the same parameter differently, so a description can't be dropped silently again.

Tested on Blockbench 5.2.1:

• 109/109 parameters of the old tools are present with unchanged types.
• verify-pixel-art 51/51, smoke and e2e tests pass.
• The shared parameters were checked with real output: render with animation + time gives a different sprite than the rest pose. export_sheet without animation gives 1 frame. A 0.5 s walk at 8 fps gives 4 frames. 8 mirrored directions give 8 tags and 32 frames.

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.

Updating

1. Overwrite both files with the new ones.
2. Restart Blockbench.
3. Restart Claude Desktop or your Claude Code session.

Coming from 1.6.x? Read the 1.7.0 notes: several tools were renamed.

get_status should show plugin_version: "1.7.1".

v1.7.0 — Fewer tools

Fewer tools: 82 → 69

Rarely used tools are now grouped into one tool with an action argument. Clients that load every tool schema up front, such as Claude Desktop, now carry about 9k fewer characters on every turn. The pixel-art tools account for most of the saving because their ~30 shared style options are now listed once.

New tool	Actions	Replaces
project_file	open, save, export, export_animations, import, get_json, switch_tab, close	open_project, save_project, export_model, export_animations, import_model, get_model_json, select_project_tab, close_project
uv	inspect, set_cube, set_mesh, auto	inspect_uv, set_cube_uv, set_mesh_uv, auto_uv
display_transforms	get, set	get_display_transforms, set_display_transforms
pixel_art	render, export_sheet, presets	render_pixel_art, export_pixel_sprites, pixel_art_presets

Each action checks its own parameters. A missing required field, or a parameter that belongs to another action, returns a clear error.

Breaking: the old tool names are gone. Saved prompts or scripts that call them by name need the new name plus action.

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.

Updating from 1.6.x

1. Overwrite both files with the new ones.
2. Restart Blockbench.
3. Restart Claude Desktop or your Claude Code session (the tool list is read at startup).

get_status should show plugin_version: "1.7.0".

v1.6.1 — Security fix

Security fix — updating is recommended

In 1.6.0 and earlier, while Blockbench and the MCP server were running, any website open in your browser could connect to the ws://127.0.0.1:8188 bridge and run code on your computer through eval_code.

In 1.6.1 the bridge accepts only connections without an Origin header (Node) and the Blockbench window (file://). Connections from websites are refused during the handshake. Test: scripts/verify-bridge-origin.mjs.

Other changes

• README rewritten: installing from a release, update steps, Blockbench 5.2 features, a security section, the low-poly example build script.
• npm run build:release: a single-file server with bundled dependencies. This release's files were built with it.

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.

Updating from 1.6.0

1. Overwrite both files with the new ones.
2. Restart Blockbench.
3. Restart Claude Desktop or your Claude Code session.

get_status should show plugin_version: "1.6.1".

v1.6.0 — Low-poly character tools

• Mesh painting: paint_texture, paint_faces and get_texture now target mesh faces too. The UV
  polygon is clipped pixel-exact, and space: "world" gradients are computed per texel. On meshes, a
  direction name ("up") selects every face pointing that way. inspect_uv reports mesh UV problems
  and texel density.
• unwrap_mesh: connected mesh faces merge into islands. Seam control, per-part density
  (density_scale), and existing paint carried over to the new layout.
• edit_mesh: Blockbench's extrude, inset, solidify, loop cut, merge, dissolve, create/invert face
  and split tools, plus subdivide, bevel, delete and merge_meshes. Steps chain with
  select: "previous".
• add_loft: box, round or custom-profile limbs and tubes from rings. transform_mesh: taper, bend,
  twist, scale, rotate, move, smooth, jitter.
• bake_texture: light direction, ray-traced ambient occlusion, convex edge highlights and concave
  crease shadows, height gradient and grain. The result snaps to a hue-shifted pixel-art ramp derived
  from each texel's own color.
• palette: hue-shifted ramps, color extraction, locking to auto / fixed palettes / ramps (with
  dithering).
• compare_reference: silhouette IoU against a reference image, aspect ratio and per-band width
  difference, overlay image. project_reference: projects the reference onto visible, unoccluded
  texels.
• record_build: captures a frame from a fixed camera on every edit and writes an animated GIF at
  the end.
• Fix: add_mesh_primitive generated cylinders, cones, pyramids, tori and planes inside out, which
  made extrude go inward. Cylinder and cone caps with more than 4 sides (n-gons) also failed; they are
  now generated as triangle fans.

Installation

1. Download blockbench_mcp.js and mcp-server.js (or unzip the archive). No npm install needed: the server is bundled with its dependencies.
2. Blockbench → File → Plugins → Load Plugin from File → blockbench_mcp.js.
3. Add it to Claude:

claude mcp add --scope user blockbench -- node /path/to/mcp-server.js

Requires Node.js 18+.