BlockbenchMCP

:uk: English · :ru: Русский

Connect Blockbench to AI assistants (OpenCode, Claude, and others) via the Model Context Protocol (MCP). The AI can directly control your active Blockbench project: create and delete cubes, inspect the model and its element structure.

Architecture

AI assistant (MCP) ←→ mcp-server (Node.js) ←Socket.IO:9999→ mcp-plugin (Blockbench)

• apps/mcp-plugin — Blockbench plugin. Receives commands over Socket.IO (port 9999) and executes them in the current project.
• apps/mcp-server — MCP server. Implements the MCP protocol over stdio and forwards commands to the plugin.
• packages/shared — shared TypeScript types.

Tools

Tool	Description
blockbench.hello	Checks the connection to Blockbench
blockbench.get_project_info	Info about the current project (format, texture size, element/texture/animation counts)
blockbench.list_elements	Lists elements (cubes) in the project with uuid and name
blockbench.add_cube	Creates a cube (position, size, auto-UV, shade, color, uv_offset)
blockbench.remove_element	Removes an element by name or uuid

Installation

Prerequisites

• Blockbench (current version, tested on 5.x)
• Node.js 20+
• pnpm (npm install -g pnpm)

1. Build

git clone https://github.com/Golub4ik-Official/blockbench-mcp.git
cd blockbench-mcp
pnpm install
pnpm build

Artifacts are written to:

• apps/mcp-plugin/dist/mcp_socketio_plugin.js — the plugin file
• apps/mcp-server/dist/index.js — the MCP server

For end users: a ready-built plugin file (mcp_socketio_plugin.js) is attached to every release — no build required.

2. Install the Blockbench plugin

1. Open Blockbench.
2. File → Plugins → Load Plugin from File → select apps/mcp-plugin/dist/mcp_socketio_plugin.js.
3. Enable the plugin (checkbox next to "MCP Plugin").
4. After it loads, the "MCP Commands" panel appears (on the right) — it shows the command history and connection status.

3. Configure the MCP server in your assistant

Register the MCP server in your assistant's config. OpenCode example (opencode.json):

{
  "mcp": {
    "blockbench": {
      "type": "local",
      "command": ["node", "C:/path/to/blockbench-mcp/apps/mcp-server/dist/index.js"],
      "enabled": true
    }
  }
}

Claude Desktop example (claude_desktop_config.json):

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

4. Usage

1. Open Blockbench and create a project (File → New → Block model).
2. Start or restart your assistant so it picks up the MCP server.
3. Ask the assistant, for example: "Create a generator like in Industrial Craft 2 — case, front panel, and an output slot."
4. Cubes are added to the active Blockbench project.

Development

# Watch-build the plugin (rebuilds on changes)
cd apps/mcp-plugin && pnpm dev

# Rebuild the MCP server
cd apps/mcp-server && pnpm build

After editing plugin code, rebuild it and reload it in Blockbench: File → Plugins → Master → Reload.

Releases

Releases are created from tags. The GitHub Actions workflow builds the plugin and attaches mcp_socketio_plugin.js to the release:

git tag v0.3.0
git push origin v0.3.0

Troubleshooting

• "ERROR: Blockbench plugin is not connected" — the plugin is not loaded or Blockbench is closed. Load the plugin and check the "MCP Commands" panel.
• Port 9999 is busy — close the conflicting process or restart the MCP server.
• Timed out — Blockbench did not respond within 30 seconds. Make sure a project is open and the plugin is active.
• The addElement method is not found — use the current plugin version (from a release); old builds used a broken API for older Blockbench versions.

License

MIT — see LICENSE.