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.