Blockbench MCP — personal fork

Lets an AI assistant (Claude Desktop, Claude Code or any other MCP client) build, texture, animate and export models inside Blockbench through the Model Context Protocol. This fork is tuned for Minecraft / GeckoLib cube models.

📌 About this fork

🇬🇧 English

• The original project is Blockbench MCP by enfpdev — enfp-dev-studio/blockbench-mcp. The foundation of this repository (the MCP server ↔ Blockbench plugin bridge) is their work; all credit for it goes to them.

• Many tool definitions were ported from jasonjgardner/blockbench-mcp-project.

• I (Nokedli25TTV) only extended it for my own use — Minecraft / GeckoLib modding. It is not sold, not monetized, and made without any intent of profit. No support or updates are promised.

• The extensions were written with AI assistance (Claude Code, OpenAI Codex). They are covered by automated tests against a mock Blockbench and were partly tried in real Blockbench, but they may still contain bugs.

• If you use it, you do so at your own risk: back up your .bbmodel files, read the code before trusting it, and keep in mind that the risky_eval tool can run arbitrary JavaScript inside Blockbench.

• The project stays under the MIT License; the original copyright notice is kept in LICENSE. What changed compared to the original: see the commit history and ARCHITECTURE.md.

🇭🇺 Magyarul

• Az eredeti projekt a Blockbench MCP, enfpdev munkája — enfp-dev-studio/blockbench-mcp. Ennek a repónak az alapja (az MCP szerver ↔ Blockbench plugin híd) az ő munkájuk, minden érdem az övék.

• Számos tool-definíció a jasonjgardner/blockbench-mcp-project projektből lett átvéve.

• Én (Nokedli25TTV) csak továbbfejlesztettem saját felhasználásra — Minecraft / GeckoLib modolás. Nem árulom, nem pénzelem, semmilyen profitszerzési célja nincs. Támogatást és frissítéseket nem ígérek.

• A fejlesztések mesterséges intelligencia segítségével készültek (Claude Code, OpenAI Codex). Automatikus tesztek ellenőrzik őket egy szimulált Blockbench ellen, és részben valódi Blockbenchben is ki lettek próbálva, de tartalmazhatnak hibákat.

• Ha használod, a saját felelősségedre teszed: készíts biztonsági mentést a .bbmodel fájljaidról, nézd át a kódot, mielőtt megbízol benne, és ne feledd, hogy a risky_eval tool tetszőleges JavaScriptet futtathat a Blockbenchben.

• A projekt továbbra is MIT-licenc alatt áll; az eredeti szerzői jogi közlemény a LICENSE fájlban megmaradt. Hogy mi változott az eredetihez képest: lásd a commit-előzményt és az ARCHITECTURE.md fájlt.

Related MCP server: Blockbench MCP

✨ What it can do

• Build a model in one call — a whole bone hierarchy plus its cubes with create_cubes, with guardrails: unique names, pivots first, one rotation axis per bone (multi-axis = nested bones).

• Texture precisely — pack_uv gives every cube its own atlas region, validate_uv catches overlaps before painting, shade_cubes paints every part in its exact colour in one call, and there are pixel-art palettes and paint tools for hand work.

• Animate — create animations, write many bones' keyframes at once (set_keyframes), read back exactly what was stored, measure a bone's world rotation / position numerically, and lint a whole animation — including "does it go through the floor?" — with check_animation. Every tool uses the values Blockbench shows; the exporter handles the GeckoLib file convention.

• See the result — screenshots from any camera angle, also of a specific animation frame (capture_screenshot with time).

• Export for GeckoLib — .geo.json via export_model plus .animation.json via export_animations.

• Stay safe — edits are normal Blockbench undo steps; save_checkpoint / undo / redo; validate_model checks the rules in MODELING_CONSTRAINTS.md before export.

• Guide the AI — eight bundled skill guides (modeling, texturing, animation, pixel shading, …) that the server tells the assistant to read before it starts.

🏗️ How it works

AI client (Claude Desktop / Claude Code)
        │  MCP over stdio
        ▼
mcp-server  (Node — apps/mcp-server)      ── Socket.IO bridge on port 9999 ──▶
                                                        mcp-plugin (runs inside Blockbench — apps/mcp-plugin)
                                                        calls the Blockbench API, answers every call

• The server speaks MCP to the AI client and forwards each tool call to the plugin, waiting for its answer (each call has its own timeout).

• The plugin is a Socket.IO client: when Blockbench loads it, it connects to 127.0.0.1:9999 by itself and reconnects automatically when the server restarts. There is no "Connect" button.

• The bridge is local-only: it listens on 127.0.0.1 and refuses connections from web pages.

• Several AI clients can share Blockbench. The first server to start owns port 9999; any later one (e.g. Claude Code while the Claude app is open) joins it as a relay and sends its calls through it. If the owner quits, a relay takes over within a few seconds and the plugin reconnects to it.

More detail: ARCHITECTURE.md.

📦 Requirements

• Blockbench desktop app (the plugin is desktop-only; a recent 5.x version is recommended)

• Node.js 18+

• pnpm 10 — npm install -g pnpm

🛠️ Installation

1. Clone and build

git clone https://github.com/Nokedli25TTV/Blockbench-MCP.git
cd Blockbench-MCP
pnpm install
pnpm build

This produces the server (apps/mcp-server/dist/index.js) and the plugin (apps/mcp-plugin/dist/mcp_socketio_plugin.js).

2. Load the plugin into Blockbench

1. Open Blockbench → File → Plugins.

2. Choose Load Plugin from File and select apps/mcp-plugin/dist/mcp_socketio_plugin.js.

3. The MCP Command History panel appears on the right; it lists every command the AI sends.

3. Connect your AI client (pick ONE)

Claude Desktop — add this to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "blockbench": {
      "command": "node",
      "args": ["C:/path/to/Blockbench-MCP/apps/mcp-server/dist/index.js"]
    }
  }
}

Claude Code:

claude mcp add blockbench -- node C:/path/to/Blockbench-MCP/apps/mcp-server/dist/index.js

4. Check that it works

Open or create a model in Blockbench, then ask the assistant to call get_project_info. The reply contains plugin_build (the loaded plugin version) and tool_count. If you get [NOT_CONNECTED], see Troubleshooting.

⚙️ Configuration

To set the profile, add "env": { "BLOCKBENCH_MCP_PROFILE": "full" } next to "args" in the Claude Desktop config, or pass -e BLOCKBENCH_MCP_PROFILE=full to claude mcp add.

🧰 Tools

Every tool carries MCP annotations (readOnlyHint / destructiveHint), so clients can tell reads from edits. Failures start with a stable code: [NOT_CONNECTED], [TIMEOUT], [NO_PROJECT], [DUPLICATE_NAME], [NOT_FOUND], [MISSING_TEXTURE], [ILLEGAL_ROTATION], [FORMAT_UNSUPPORTED], [UV_ERROR], [INVALID_INPUT] or [ERROR]. Non-fatal notes arrive as ⚠️ lines in a successful reply.

💬 Usage

Example requests

• "Create a new GeckoLib project called dagger and build a dagger stuck in the ground at an angle."

• "Pack the UVs, then texture the blade steel #b9c2cb with a dark edge, the guard gold and the grip brown."

• "Add a 2-second looping idle animation where the head sways a few degrees."

• "Show me the model at 1.0 s of the idle animation from the front."

• "Validate the model and export the .geo.json and .animation.json to my mod's assets folder."

Tips for fast sessions

Measured over ~1,700 real calls: a tool call takes about 40 ms, but the pause between calls is about 10 s — the session speed comes from how many round-trips there are and how much the AI has to read.

1. Batch: create_cubes, modify_cubes, shade_cubes, set_keyframes do in one call what used to take dozens. They are all-or-nothing and one undo step each.

2. Read narrowly: use get_scene_tree with bone_names / include_faces:false on big models.

3. Screenshots sparingly: they are downscaled to 800 px (max_size); use set_camera_angle screenshot:false to move the camera and take one screenshot at the end.

4. Trust the replies: write tools echo what they stored (e.g. set_keyframes lists every channel).

🔁 After changing the code

Confirm with get_project_info: plugin_build is stamped at build time as <version>+<UTC date.time>.<git commit> (-dirty = built with uncommitted changes), and mcp_bridge.server_version shows the server.

🐛 Troubleshooting

🔧 Development

Blockbench-MCP/
├── apps/
│   ├── mcp-server/        # MCP server: tool registrations, Socket.IO bridge (src/index.ts), skill loader
│   │   ├── test/          # mock-Blockbench harness + full-model test
│   │   └── toolchain-e2e.mjs
│   └── mcp-plugin/        # Blockbench plugin: one handler per tool (src/mcp_socketio_plugin.ts)
├── packages/shared/       # tool-name types, model validation, pixel-art palettes
├── skills/                # the 8 skill guides served to the AI
├── tools/                 # usage report, plugin typecheck ratchet
├── .github/workflows/     # CI: build, typecheck, tests on Ubuntu + Windows
├── ARCHITECTURE.md        # how it all fits together
├── MODELING_CONSTRAINTS.md
└── AGENTS.md

pnpm build                                  # build server + plugin
pnpm --filter mcp-server dev                # rebuild the server on change
pnpm --filter mcp-plugin dev                # rebuild the plugin on change
pnpm test                                   # model test + e2e against a mock Blockbench (build first)
pnpm typecheck                              # server tsc + plugin error ratchet
pnpm report                                 # usage report from Claude's logs (add --since 2026-09-01)

The tests start the real server on a random port with a simulated Blockbench, so they need neither Blockbench nor port 9999. They check the server and its wiring (including the shared bridge: relay, takeover, resend); the Blockbench API calls themselves are only exercised in real Blockbench. CI runs build, typecheck and tests on every push to main.

The plugin still has 56 known type errors from outdated blockbench-types (APIs that exist at runtime but not in the typings). pnpm typecheck fails only if that number goes up.

pnpm report reads the Claude app's mcp-server-blockbench.log and Claude Code's mcp-logs-blockbench/*.jsonl: call counts, latency, think time between calls, error codes, per-tool numbers, and bridge events (port conflicts, relay joins, takeovers). Nothing is sent anywhere.

Adding a tool touches three places: the registerTool call in apps/mcp-server/src/index.ts, a handler plus its dispatch entry in apps/mcp-plugin/src/mcp_socketio_plugin.ts, and the ToolType union in packages/shared/src/types.ts — plus a mock handler and a check in the tests.

⚠️ Limitations & security

• risky_eval runs arbitrary JavaScript inside Blockbench, with the app's permissions. Only allow it when you understand the code being run.

• The bridge is local-only: it listens on 127.0.0.1:9999 (not reachable from the network) and refuses Socket.IO connections that come from a web page (an http/https or sandboxed null Origin), so a site open in your browser can't pose as Blockbench. The relay endpoint that lets a second server share the bridge accepts only requests with no Origin, a custom header and a 127.0.0.1/localhost Host. Other programs running on your own machine can still connect.

• export_model / export_animations can write files to the path you give (Blockbench asks for file system permission).

• GeckoLib renders cubes only — mesh elements are dropped on export (validate_model warns about it).

• Always save your work before large AI-driven edits; most tool edits are undoable, but a crash is not.

📄 License

MIT — see LICENSE. The original copyright notice is kept.

🙏 Acknowledgments

• Original project: enfp-dev-studio/blockbench-mcp by enfpdev

• Tool definitions ported from jasonjgardner/blockbench-mcp-project

• Inspired by BlenderMCP

• Built with the Model Context Protocol

• Thanks to the Blockbench community for the amazing 3D modeling tool

Disclaimer: This is a third-party integration and not officially affiliated with Blockbench, Mojang, GeckoLib or Anthropic.