BlockbenchMCP - Blockbench Model Context Protocol Integration

BlockbenchMCP connects Blockbench to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blockbench. This integration enables AI-assisted 3D modeling, texture creation, and block model manipulation.

🚀 Features

Two-way communication: Connect Claude AI to Blockbench through a socket-based server
Real-time command tracking: Monitor all MCP commands with a dedicated history panel
Model manipulation: Create, modify, and delete block models in Blockbench
Live feedback: Get instant responses from Blockbench operations
Extensible architecture: Easy to add new tools and capabilities

🏗️ Components

The system consists of two main components:

Blockbench Plugin (apps/mcp-plugin): A Blockbench plugin that creates a socket server within Blockbench to receive and execute commands
MCP Server (apps/mcp-server): A Node.js server that implements the Model Context Protocol and connects to the Blockbench plugin

📦 Project Structure

blockbench-mcp/
├── apps/
│   ├── mcp-server/      # MCP server implementation
│   └── mcp-plugin/      # Blockbench plugin
└── packages/
    └── shared/          # Shared TypeScript types

�️ Installation

Prerequisites

Blockbench 4.0 or newer
Node.js 18.0 or newer
pnpm package manager

Install pnpm if you haven't already:

npm install -g pnpm

1. Clone and Setup

git clone https://github.com/enfpdev/blockbench-mcp.git
cd blockbench-mcp
pnpm install

2. Build the Project

pnpm build

3. Install the Blockbench Plugin

Build the plugin: cd apps/mcp-plugin && pnpm build
Open Blockbench
Go to File > Plugins > Load Plugin from File
Select the built plugin file from apps/mcp-plugin/dist/
Enable the plugin by checking the box next to "MCP Plugin"

4. Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

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

🎮 Usage

Starting the Connection

In Blockbench, open the plugin panel (if not visible, go to View > Panels)
Find the "MCP Plugin" panel
Click "Connect to MCP Server"
The plugin will start listening on port 9999

Using with Claude

Once the configuration is set in Claude Desktop and the plugin is running in Blockbench, you'll see a hammer icon with tools for Blockbench MCP.

Capabilities

Get model and project information
Create, delete, and modify block models
Apply textures and materials
Execute custom modeling operations
Real-time command history tracking

Example Commands

Here are some examples of what you can ask Claude to do:

"Create a simple sword model with proper proportions"
"Add a crossguard to the existing sword model"
"Create a chest model with opening animation"
"Generate a pickaxe tool with different material variants"
"Show me the current model structure and elements"
"Create a character head with facial features"

🔧 Development

Development Mode

# Start both server and plugin in development mode
pnpm dev

# Or start individually
cd apps/mcp-server && pnpm dev
cd apps/mcp-plugin && pnpm dev

Version Management

This project uses Changesets for version management:

# Record changes
pnpm changeset

# Update versions
pnpm version

# Build all packages
pnpm build

🐛 Troubleshooting

Connection issues: Make sure the Blockbench plugin is running and the MCP server is configured in Claude Desktop
Port conflicts: The plugin uses port 9999 by default. Make sure no other application is using this port
Plugin not loading: Verify that the plugin file is properly built and Blockbench version is compatible
Command timeouts: Try simplifying your requests or breaking them into smaller steps

🔧 Technical Details

Communication Protocol

The system uses Socket.IO for real-time communication between components:

WebSocket connection on port 9999
JSON-based commands with type and payload structure
Event-driven architecture for responsive interactions

Architecture

Claude AI ← MCP Protocol → MCP Server ← Socket.IO → Blockbench Plugin

⚠️ Limitations & Security Considerations

The plugin allows executing code within Blockbench, which can be powerful but potentially risky
Always save your work before using experimental features
Complex operations might need to be broken down into smaller steps
Network communication happens over localhost only for security

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

� License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

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.

BlockbenchMCP