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.

Related MCP server: Blockbench MCP

Tools

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.