BlockbenchMCP

Let an AI build Minecraft models, textures and animations directly inside Blockbench — through the Model Context Protocol.

BlockbenchMCP gives an AI assistant a live connection to a running Blockbench window. The model can start a project from the start screen, build geometry (bones + cubes), paint textures procedurally, author keyframe animations (including GeckoLib), install Blockbench plugins, move the camera, and take screenshots so it can look at its own work and refine it — all without you touching the editor.

It was used to model, texture and animate a full GeckoLib grizzly bear (walk / run / sleep / attack) end-to-end from a single prompt.

---

Table of contents

• How it works
• Features
• Requirements
• Installation
• Connecting your AI client
• Tool reference
• Example: an animated GeckoLib bear
• Troubleshooting
• Security
• Limitations
• Development
• License

---

How it works

There are two pieces:

Piece	Runs where	Responsibility
Bridge plugin — plugin/blockbench_mcp.js	Inside Blockbench (desktop)	Hosts a local HTTP endpoint on 127.0.0.1:8787 (built on Node's net module) and runs each command against the Blockbench API on the renderer thread.
MCP server — src/ → dist/	A Node process your AI client launches	Exposes Blockbench as MCP tools (stdio transport) and forwards every call to the bridge.

┌────────────┐   stdio (MCP)   ┌──────────────────┐   HTTP 127.0.0.1:8787   ┌─────────────────────┐
│  AI client │ ──────────────▶ │  blockbench-mcp  │ ──────────────────────▶ │  Blockbench + plugin │
│ (Claude…)  │ ◀────────────── │   (Node server)  │ ◀────────────────────── │   (live editor)      │
└────────────┘                 └──────────────────┘                         └─────────────────────┘

Features

• 🧱 Modeling — create bones (groups) and cubes one at a time or in bulk (add_groups / add_cubes build a whole posed skeleton in one call), with full rotation and inflate; edit/move/reparent/delete, and read the outliner tree.
• 🎨 Texturing — create textures, paint procedurally (pixels, rects, lines, circles, ellipses, polygons, dither, noise, gradients), auto-shade every cube face with detail_cubes (no flat or untextured gaps), and place features in face-relative coordinates with paint_faces.
• 🎬 Animation — create animations, add keyframes in bulk for any bone/channel with interpolation control (linear / catmullrom / step / bezier).
• 📸 Vision — screenshot, screenshot_views (several angles at once) and get_texture return images inline so the model can see and iterate, and check_model audits for problems.
• 🧠 Guidance — get_guide returns a modeling/texturing playbook so the AI builds detailed, rotated models instead of a few flat boxes.
• 🧩 Plugins — search, install (by store id, URL, or file) and uninstall Blockbench plugins, so the AI can set up formats like GeckoLib itself.
• 🔧 Escape hatch — execute_script runs arbitrary Blockbench JS for anything not covered by a dedicated tool.
• 🟢 40 tools total, all over a single local connection.

Requirements

• Blockbench desktop app, version 4.8+ (the web app cannot host the bridge — see Limitations).
• Node.js 18+ (for global fetch).
• An MCP-capable client (Claude Code, Claude Desktop, Cursor, etc.).

Installation

1. Install the bridge plugin in Blockbench

1. Open the desktop Blockbench app.
2. File ▸ Plugins ▸ Load Plugin from File and select plugin/blockbench_mcp.js. (Alternatively copy it into your Blockbench plugins folder.)
3. On first start the plugin asks for network permission (it needs the net module to host the local server). Choose “Always allow for this plugin.”
4. A toast confirms “MCP server started on port 8787.”
   • Toggle the server any time: Tools ▸ Start / Stop MCP Server
   • Change the port: Settings ▸ General ▸ MCP Server Port (default 8787)

Verify it's up:

curl http://127.0.0.1:8787/ping
# {"ok":true,"protocol":1,"blockbench_version":"5.x.x","is_app":true,"has_project":false}

2. Build the MCP server

git clone https://github.com/sosadly/blockbench-mcp.git
cd blockbench-mcp
npm install
npm run build

Connecting your AI client

Point your client at dist/index.js over stdio. Use an absolute path.

Claude Code — .mcp.json in your project (or claude mcp add):

{
  "mcpServers": {
    "blockbench": {
      "command": "node",
      "args": ["/absolute/path/to/blockbench-mcp/dist/index.js"],
      "env": { "BLOCKBENCH_MCP_PORT": "8787" }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "blockbench": {
      "command": "node",
      "args": ["C:\\path\\to\\blockbench-mcp\\dist\\index.js"]
    }
  }
}

Env var	Default	Purpose
BLOCKBENCH_MCP_PORT	8787	Must match the plugin's port setting.
BLOCKBENCH_MCP_HOST	127.0.0.1	Bridge host.

Tool reference

Group	Tools
Status & guidance	get_status, get_guide, list_formats
Project	new_project, set_project_meta, save_project, export_project, load_project, close_project
Geometry	add_group, add_cube, add_groups, add_cubes, edit_element, delete_element, list_outliner, get_element, check_model
UV & textures	create_texture, paint_texture, detail_cubes, paint_faces, apply_texture, set_cube_uv, import_texture, resize_texture, list_textures, get_texture
Animation	create_animation, add_keyframe, add_keyframes, list_animations, remove_animation
View	set_camera_angle, screenshot, screenshot_views
Plugins	list_plugins, install_plugin, uninstall_plugin
Escape hatch	execute_script

Conventions: coordinates are Blockbench units; rotations are degrees; texture pixel ops use a top-left origin with y pointing down. add_cube returns each face's resolved UV rect; detail_cubes then base-coats every face and paint_faces lets you paint features (eyes, nose, claws) in coordinates relative to a face, so you don't compute absolute UVs by hand.

Example: an animated GeckoLib bear

The sequence an AI follows for “make a textured GeckoLib bear that can walk, run, sleep and attack”:

// 0. Read the playbook so the model comes out detailed and rotated, not boxy
get_guide {}

// 1. Install GeckoLib (adds the `geckolib_model` format)
install_plugin { "id": "geckolib" }

// 2. New project, straight from the start screen
new_project { "format": "geckolib_model", "name": "bear",
              "texture_width": 64, "texture_height": 64 }

// 3. Lay out the whole posed skeleton in one call — note the rotated bones
add_groups { "groups": [
  { "name": "body",   "origin": [0, 12, 0] },
  { "name": "head",   "origin": [0, 14, -7], "parent": "body", "rotation": [10, 0, 0] }, // nose down
  { "name": "leg_fl", "origin": [3, 8, -5],  "parent": "body", "rotation": [-6, 0, 0] },
  { "name": "leg_fr", "origin": [-3, 8, -5], "parent": "body", "rotation": [-6, 0, 0] }
  // ...hind legs, ears, muzzle, tail...
] }

// 4. Build many cubes at once (segment limbs, taper with inflate, mirror left/right)
add_cubes { "cubes": [
  { "name": "torso",   "from": [-5, 8, -7], "to": [5, 16, 7], "parent": "body" },
  { "name": "head",    "from": [-3.5, 10, -13], "to": [3.5, 16, -7], "parent": "head" },
  { "name": "muzzle",  "from": [-2, 10, -16], "to": [2, 13, -13], "parent": "head", "inflate": -0.5 }
  // ...
] }

// 5. Texture: shaded base coat on EVERY face (no gaps), then features face-relative
create_texture { "name": "bear", "width": 64, "height": 64, "fill": "#6e4a2b" }
detail_cubes   { "base": "#6e4a2b", "noise": 0.12, "bottom_dark": 0.3 }
paint_faces    { "faces": [
  { "cube": "head",   "face": "north", "ops": [
    { "type": "rect",    "x": 2, "y": 2, "width": 1, "height": 1, "color": "#0f0a05" }, // eye
    { "type": "ellipse", "x": 3, "y": 4, "width": 2, "height": 2, "color": "#140e08" }  // nose
  ] }
] }

// 6. Animate (bulk keyframes, smooth interpolation)
create_animation { "name": "animation.bear.walk", "loop": "loop", "length": 1.2 }
add_keyframes {
  "animation": "animation.bear.walk",
  "keyframes": [
    { "bone": "leg_fl", "channel": "rotation", "time": 0.0, "value": [28, 0, 0], "interpolation": "catmullrom" },
    { "bone": "leg_fl", "channel": "rotation", "time": 0.6, "value": [-28, 0, 0], "interpolation": "catmullrom" },
    { "bone": "leg_fl", "channel": "rotation", "time": 1.2, "value": [28, 0, 0], "interpolation": "catmullrom" }
  ]
}

// 7. Review from every side + audit, fix what you see, then repeat 4–7
screenshot_views { "views": ["isometric_right_front", "front", "left", "back"] }
check_model {}

// 8. Save / export
save_project   { "path": "D:/models/bear.bbmodel" }
export_project { "path": "D:/models/bear.geo.json" }

Troubleshooting

Blockbench shows “server stopped” and Start does nothing. The plugin needs the net module. When you click Start MCP Server, Blockbench shows a permission dialog — choose “Always allow for this plugin.” If you previously denied it, revoke and retry from the plugin's context menu, or restart Blockbench.

MCP tools fail with “Cannot reach Blockbench on 127.0.0.1:8787”. Make sure Blockbench is open, the plugin is loaded, and the server is running (green toast / curl .../ping works). Confirm the port in the plugin settings matches BLOCKBENCH_MCP_PORT.

“Unknown format … the matching plugin must be installed.” Plugin formats like GeckoLib's geckolib_model require install_plugin { "id": "geckolib" } first. Run list_formats to confirm the id appeared.

Console 404s about about.md / the plugin store. Harmless — Blockbench tries to fetch store metadata for the side-loaded plugin and gets a 404. It does not affect the bridge.

Security

• The bridge binds to 127.0.0.1 only — it is not reachable from your network.
• execute_script runs unsandboxed JavaScript inside Blockbench. Only connect MCP clients you trust, and prefer the dedicated tools over execute_script where possible.

Limitations

• Desktop only. The bridge relies on Node modules (net), which the Blockbench web app does not expose to plugins.
• One Blockbench window. The bridge talks to whichever project is currently active.
• Box-UV packing is up to the caller; add_cube returns resolved face UVs to make this manageable.

Development

npm run dev     # tsc --watch
npm run build   # one-off compile to dist/

• MCP tool definitions live in src/tools.ts; the HTTP client in src/client.ts; the server entry in src/index.ts.
• Bridge command handlers live in plugin/blockbench_mcp.js under the commands object — add a handler there and a matching tool in tools.ts to extend the surface.
• The Blockbench API used by the bridge is documented in the official type definitions.

License

MIT © sosadly

Built with the Model Context Protocol. Not affiliated with Blockbench or GeckoLib.