BlockbenchMCP

# 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: 1. **Blockbench Plugin** (`apps/mcp-plugin`): A Blockbench plugin that creates a socket server within Blockbench to receive and execute commands 2. **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: ```bash npm install -g pnpm ``` ### 1. Clone and Setup ```bash git clone https://github.com/enfpdev/blockbench-mcp.git cd blockbench-mcp pnpm install ``` ### 2. Build the Project ```bash pnpm build ``` ### 3. Install the Blockbench Plugin 1. Build the plugin: `cd apps/mcp-plugin && pnpm build` 2. Open Blockbench 3. Go to **File** > **Plugins** > **Load Plugin from File** 4. Select the built plugin file from `apps/mcp-plugin/dist/` 5. 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:** ```json { "mcpServers": { "blockbench": { "command": "node", "args": [ "/path/to/blockbench-mcp/apps/mcp-server/dist/index.js" ] } } } ``` ## 🎮 Usage ### Starting the Connection 1. In Blockbench, open the plugin panel (if not visible, go to **View** > **Panels**) 2. Find the "MCP Plugin" panel 3. Click "Connect to MCP Server" 4. 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 ```bash # 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](https://github.com/changesets/changesets) for version management: ```bash # 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. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## � License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - Inspired by [BlenderMCP](https://github.com/ahujasid/blender-mcp) - Built with the [Model Context Protocol](https://modelcontextprotocol.io/) - Thanks to the Blockbench community for the amazing 3D modeling tool --- **Disclaimer:** This is a third-party integration and not officially affiliated with Blockbench.