Blockbench MCP

An MCP server and a companion Blockbench plugin that let Claude control Blockbench.

With it, Claude builds models, unwraps UVs, paints textures, adds bones and animations, checks the
result with screenshots, and exports the model to any format Blockbench supports. Besides
Minecraft-style cube models, it can make low-poly, hand-painted characters. It can also turn a model
into pixel art sprites for 2D games.

Every change goes into Blockbench's undo history. Press Ctrl+Z to revert any step you don't like.

If you use version 1.6.0 or older, update. In older versions, while Blockbench and the MCP server
were running, any website open in your browser could connect to the bridge and run code on your
computer. 1.6.1 closes this. Details: Security.

What it can do

What Blockbench 5.2 adds

5.2 also unlocks: texture layer groups, IK with poles, movable reference models in the scene,
reference images shown as 3D panels, Java 26.3 shade_direction_override, the cushion skin template,
Molang variable_placeholders, bounding boxes, the embedded and on_shelf display slots, and glTF
merge_armature. The features field in the get_status output shows which of these your Blockbench
has.

Installation

Quick start: prebuilt release

1. Download blockbench_mcp.js and mcp-server.js from the
   latest release. Both are also
   available as a zip. No npm install needed: the server is bundled with its dependencies.
2. Put both files in a permanent folder. Blockbench loads the plugin from this path; if you move the
   folder, you have to load the plugin again.
3. Install the plugin in Blockbench and
   register the server with Claude.

Build from source

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

The build creates two files in dist/:

• blockbench_mcp.js: the Blockbench plugin
• mcp-server.js: the MCP server (reads its dependencies from node_modules)

For a single-file server with dependencies bundled in, run npm run build:release.

Install the plugin in Blockbench

1. Open Blockbench and go to File → Plugins.
2. In the top-right menu, choose Load Plugin from File.
3. Select blockbench_mcp.js and accept the security prompt.

Register with Claude

Claude Code:

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

Claude Desktop: add this to the mcpServers section of %APPDATA%\Claude\claude_desktop_config.json:

"blockbench": {
  "command": "node",
  "args": ["C:\\path\\to\\mcp-server.js"],
  "env": { "BB_BRIDGE_PORT": "8188" }
}

Then fully quit Claude Desktop from the system tray and reopen it.

Both can run at the same time. The first server to take the port becomes the bridge; the others relay
their commands through it.

Check the connection

With Blockbench open, ask Claude to "check the Blockbench status". get_status should return a
connected Blockbench version. If it doesn't, see Troubleshooting.

Updating

1. Overwrite blockbench_mcp.js and mcp-server.js with the new files (or git pull and
   npm run build).
2. Restart Blockbench.
3. Restart Claude Desktop or your Claude Code session. The running server stays on the old version.

plugin_version in the get_status output should show the new version.

Recommended workflow

Building the model step by step works better than asking for everything at once. Checking a
screenshot after each step and asking for fixes is less work than fixing everything at the end.

Cube model (Minecraft-style entity)

1. Project and skeleton. Pick a format (create_project), then build the bone tree
   (add_groups), for example body > head, body > leg_fl. Animations apply to these groups, so
   don't skip this step.
2. Geometry. Place cubes inside the groups (add_cubes). Use mirror: true for symmetric legs and
   arms. Use add_planes for thin parts like fur or leaves.
3. Check. Look from the front, side and top with capture_multi_view. Fix proportions here;
   changing geometry after painting breaks the UVs.
4. Texture. First generate_texture_template, then paint_texture / paint_faces. Without the
   template, many faces share one UV area and painting one repaints the others.
5. Animation. create_animation, set_keyframes, and mirror_keyframes for left-right pairs.
   Then use validate_model to check for parts intersecting during the animation, and
   query_geometry to check that the feet touch the ground.
6. Export. project_file actions export and export_animations. For 2D games, pixel_art action export_sheet.

Example request:

Make a wolf model in the Bedrock entity format. First build only the skeleton and the shape with gray
cubes, and show me three views. If I approve, move on to the texture and a walk animation.

Low-poly, hand-painted character

Recommended order for PS1-style characters with hand-painted textures, in the free format:

1. Reference. Compare against the reference image from the same angle with compare_reference.
   The tool reports silhouette similarity (IoU) and, for each height band, how much wider or narrower
   the model is, in units.
2. Blockout. Use add_loft for arms, legs, trousers and torso: give the center and size of each
   ring and you get a tapering, bending box limb. Use an add_mesh_primitive cylinder for a hat brim,
   and a plane + edit_mesh solidify for a cape.
3. Shaping. Taper/bend/twist with transform_mesh, extrude/inset/loop cut with edit_mesh. Steps
   chain with select: "previous", so extrude → inset → extrude happens in one call. Soften boxy parts
   with bevel. Run compare_reference again after each step.
4. UV. unwrap_mesh {pixel_density: 32-64, density_scale: {"head": 2}}. Limbs unwrap as single
   strip islands. Pixels painted earlier are carried over to the new layout.
5. Flat colors. Pick color ramps with palette {action: "ramp"} and fill flat colors with
   paint_faces. On meshes, faces: ["up"] selects the upward-facing faces. Optionally, project the
   reference onto the texture with project_reference as a starting point.
6. Bake. bake_texture {layer: "shading"} paints light, AO and edge highlights as hue-shifted
   pixel-art steps. It writes to its own layer, so baking again doesn't stack shadows.
7. Cleanup. Lock stray colors to the palette with palette {action: "quantize"}.
8. Recording. Call record_build {action: "start"} at the beginning and every edit becomes a
   frame. stop at the end writes a part-by-part build GIF.

A ready-made example runs this whole workflow. It builds a four-armed, gas-masked gunslinger and
records the build as a GIF. It works in a new tab and doesn't touch your open model:

OUT=C:/output/folder node scripts/examples/build-gunslinger.mjs

Coordinate conventions

• 1 unit = 1/16 block. Y is up; the ground is y=0.
• +X is east, -Z is north. Entities are modeled facing north (-Z); the north camera preset shows the
  front.
• Rotations are in degrees, order ZYX. +X swings a hanging limb forward.

Tools

Each tool's parameters are described in its MCP schema. Claude reads them on its own.

Tips

Texture painting

• target: {element: "leg_fl", faces: "all"} paints every cube in a group in one operation. Use
  element: "*" for the whole model.
• Give gradients space: "world". Without it, the gradient restarts on every cube and multi-part
  limbs look banded. Use stops for multi-stop gradients.
• Painting shadows on a separate layer (layer) set to multiply at 50% opacity makes them easy to
  adjust later.
• Use jagged_edge for fur silhouettes and strands for fur texture.
• If the texture looks right as an image but wrong on the model, run uv action inspect first. To see a
  single face up close, get_texture crops and enlarges that face's UV region.
• If the model looks washed out or shows a grid, the cause is usually not the texture. Check
  Blockbench's brightness and pixel_grid settings.

Animation

• Keyframe values can be Molang: "math.sin(query.anim_time*360)*15".
• Times snap to the animation's FPS grid (default 24). Use snap: false when you need the exact value.
  Use edit_keyframes to retime or delete keyframes later.
• If a bone has a rest rotation, keyframe values are added on top of it; they are not absolute angles.
• For quick motion, apply_animation_preset: float, flap, swing, sway, shake, jump, flicker and more.
• Before exporting animations that use IK to Bedrock or Java, convert them to plain rotation keyframes
  with bake_ik_animation.

Pixel art

pixel_art action render doesn't produce a downscaled screenshot; it draws the model by pixel art rules.
Scale snaps to texture pixels, there is no anti-aliasing, shading uses a limited number of color
bands, and a 1 px outline is drawn around the silhouette and where parts meet.

• Views: side, front, back, top, three_quarter, top_down, isometric (2:1),
  true_isometric. Use yaw / pitch for a free angle.
• Directions: directions: 8 produces an eight-direction set. On symmetric models,
  mirror_directions: true cuts render time.
• Style: outlined (default), clean, minecraft, flat.
• Palette: the model's own colors by default. Fixed palettes like pico8, sweetie16,
  endesga32, db32, or your own hex list also work. Optional Bayer dithering.
• Sprite sheet: pixel_art action export_sheet writes animations as a single PNG plus an Aseprite-compatible
  JSON. Scale and pivot are computed once for all frames, so frames don't drift.

Ask Claude for the pixel_art action presets output to see every option.

File paths

Saving and exporting need absolute paths. get_status returns the home, desktop and temp folders;
get_project_info returns the last-used folder for each file type. Claude builds paths from these.

How it works

Claude ──stdio──► MCP server (mcp-server.js)
                       │  ws://127.0.0.1:8188
                       ▼
             Blockbench plugin (blockbench_mcp.js)

The WebSocket server runs on the MCP side and the plugin connects to it, so Blockbench doesn't ask for
network permissions. If Blockbench closes, the server keeps running. When Blockbench reopens, the
plugin reconnects on its own within a few seconds.

Browser engines slow down timers while a window is in the background. The plugin works around this, so
long operations keep running while Blockbench is minimized.

The default port is 8188. To change it, set both the BB_BRIDGE_PORT environment variable and
Settings → General → MCP Bridge Port in Blockbench to the same value.

Adding tools from another plugin

Another Blockbench plugin can add its own tools. Claude sees them next to the built-in ones as soon as
they are registered, with no server restart. Register through window.BlockbenchMCP and listen for
blockbench_mcp_ready. The event covers a plugin that loads before this one, and re-adds the tool
when the bridge plugin reloads.

let tool;
function addTools() {
  tool = BlockbenchMCP.registerTool({
    name: 'count_cubes',
    title: 'Count cubes',
    description: 'Count the cubes in the open project, optionally only those whose name contains a filter.',
    inputSchema: { type: 'object', properties: { filter: { type: 'string' } } }, // JSON Schema
    annotations: { readOnlyHint: true },
  }, ({ filter }) => ({ count: Cube.all.filter((c) => !filter || c.name.includes(filter)).length }));
}

Plugin.register('my_plugin', {
  onload() {
    if (window.BlockbenchMCP) addTools();
    window.addEventListener('blockbench_mcp_ready', addTools);
  },
  onunload() {
    tool?.delete();
    window.removeEventListener('blockbench_mcp_ready', addTools);
  },
});

• name: 1–64 characters of A-Z a-z 0-9 _ - .. A name a built-in or another plugin already uses
  is refused.
• description is required. It is all Claude reads to decide when to call the tool.
• inputSchema is optional and must have type: "object". The server does not check arguments
  against it; the handler should.
• The handler may be async. A returned string is sent as text, anything else as JSON. To send
  images, put a PNG data URL in __image (or an array of them in __images) on the returned object.
  A thrown error comes back as the tool's error message. Calls time out after 120 seconds.
• registerTool returns an object with delete(), which removes the tool again.

Security

• The bridge listens only on this computer (127.0.0.1). Other devices on the network can't
  connect.
• Websites can't connect to the bridge (1.6.1). The server accepts only connections without an
  Origin header (Node) and the Blockbench window (file://), and refuses everything else during the
  handshake. Programs running on your computer can still connect; they already run with your
  permissions, so this adds no extra risk.
• eval_code can't freeze Blockbench. Node modules that open a permission dialog (fs,
  child_process and similar) are refused before the code runs. allow_native_modules: true opts
  out; the Blockbench window must then be in the foreground.
• Every change can be undone. Tools write to Blockbench's undo history.
• A .bbmodel file you share may contain local paths. Blockbench saves the full path of the
  animation file, which can include your username. Check the file before sharing it.

Development

npm run build           # plugin and server
npm run build:release   # single-file server with bundled dependencies (for releases)
npm run typecheck

You don't need to restart Blockbench after changing the plugin:

node scripts/call-tool.mjs eval_code '{"code":"setTimeout(() => Plugins.devReload(), 300); \"ok\"","undo":false}'

An open Claude session fixes its tool list when the server starts. To try a new tool without
restarting the session:

node scripts/call-tool.mjs pixel_art '{"action":"render","view":"isometric","size":64}' --images e2e-output/tmp

Tests

Run any of them with node scripts/<name>.

Troubleshooting

• "Blockbench is not connected"
  1. Is Blockbench running?
  2. Is the plugin installed and enabled under File → Plugins?
  3. Is the port the same on both sides? (Default 8188.)
• I updated but the old behavior remains. Restart the Claude session. The running server process
  keeps using the old file.
• Long operations time out while the window is in the background. timers.unthrottled in the
  get_status output should be true. If it's false, bring the Blockbench window to the front.
• Logs
  • Claude Desktop: %APPDATA%\Claude\logs\mcp-server-blockbench.log
  • Blockbench: Ctrl+Shift+I → Console → [MCP] lines