MCP server for Rubik's Cube solving with real-time 3D visualization and MCP UI integration
npm install rubiks-cube-mcp-serverA Model Context Protocol (MCP) server that provides AI agents with the ability to solve Rubi### 4. finish
Complete the Rubik's Cube game session.
Parameters:
- gameId (string): The game session ID
Returns:
- Final game statistics
- Move history
- Completion status with congratulations messageles through systematic manipulation and real-time visualization.
- Interactive Cube Manipulation: Execute standard Rubik's Cube moves (U, D, L, R, F, B and their variations)
- Configurable Difficulty: Set scramble difficulty from 1-100 moves for varied challenge levels
- MCP UI Integration: Interactive web components delivered directly from the MCP server with clickable game links
- Game Session Management: Join existing games or create new ones with customizable settings
- 3D Real-time Visualization: Beautiful 3D cube visualization using Three.js and WebGL
- WebSocket Live Updates: Real-time state synchronization between MCP server and web interface
- Mouse Interaction: Rotate and examine the 3D cube with mouse controls
- Recursive Workflow: AI agents can systematically work through cube solving using nextAction guidance
- State Tracking: Complete move history and current cube state monitoring
- Solution Detection: Automatic detection when the cube is solved with celebration effects
- Node.js 18.x or higher
- npm or yarn
``bash`
cd rubiks-cube-mcp-server
npm install
`bash`
npm run build
`bash`
npx rubiks-cube-mcp-server
This will start both:
- MCP server on stdio (for AI agent communication)
- Web visualization server on http://localhost:3000
To use this MCP server with Claude Desktop, add the following to your claude_desktop_config.json:
`json`
{
"mcpServers": {
"rubiks-cube": {
"command": "npx",
"args": ["rubiks-cube-mcp-server"]
}
}
}
Configuration file locations:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
After adding the configuration, restart Claude Desktop to load the MCP server.
Initialize a new Rubik's Cube game session.
Parameters:
- scramble (optional, boolean): Whether to scramble the cube initially (default: true)difficulty
- (optional, number): Number of scramble moves (1-100, default: 20)
Returns:
- MCP UI resource with clickable game link
- Game ID for the session
- Initial cube state with difficulty level
- Visualization URL
- Next action guidance
Join an existing Rubik's Cube game session.
Parameters:
- gameId (string): The game session ID to join
Returns:
- Current cube state
- Game metadata including difficulty
- Next action guidance
Execute a move on the Rubik's Cube.
Parameters:
- gameId (string): The game session IDmove
- (string): Standard cube notation (U, D, L, R, F, B, U', D', L', R', F', B', U2, D2, L2, R2, F2, B2)
Returns:
- Updated cube state
- Move execution confirmation
- Total moves count
- Next action guidance
Complete the Rubik's Cube game session.
Parameters:
- gameId (string): The game session ID
Returns:
- Final game statistics
- Move history
- Completion status
The server uses standard Rubik's Cube notation:
- U: Up face clockwise
- D: Down face clockwise
- L: Left face clockwise
- R: Right face clockwise
- F: Front face clockwise
- B: Back face clockwise
- ': Counter-clockwise (e.g., U')
- 2: Double turn (e.g., U2)
`text
Agent: "Start a new Rubik's cube puzzle with easy difficulty"
→ startCube tool called with { scramble: true, difficulty: 5 }
→ Returns MCP UI resource with clickable game link + game state
Agent: "Join existing game cube_123456789_abc"
→ joinGame tool called with gameId
→ Returns current cube state and game metadata
Agent: "Execute move U"
→ manipulateCube tool called with move "U"
→ Returns updated state and nextAction guidance
Agent: "Continue solving..."
→ Recursive manipulateCube calls until solved
→ finish tool called when complete with celebration message
`
Visit http://localhost:3000/game/{gameId} to see:
- Real-time 3D cube representation
- Color-coded faces (White, Yellow, Red, Orange, Blue, Green)
- Move counter and history
- Interactive move buttons
- Solution status indicator
The server now includes MCP UI integration for enhanced user experience:
- Clickable Game Links: When starting a new game, the server returns an interactive UI resource with a clickable link to the web visualization
- Game Session Management: Support for joining existing games created by other users or sessions
- Visual Feedback: Clear indication of game status, difficulty level, and next actions
When you call the startCube tool, you'll receive:
1. A clickable UI resource linking directly to the game
2. Complete game state data in JSON format
3. Metadata including difficulty level and next action guidance
Use the joinGame tool with a game ID to participate in games created elsewhere:
- Perfect for collaborative solving
- Maintains full game state and history
- Seamless integration with existing MCP workflow
- MCP Protocol: Standard Model Context Protocol for AI agent communication
- MCP UI Integration: Interactive web components with @mcp-ui/server for clickable resources
- 3D Rendering: Three.js WebGL-based 3D cube visualization
- Real-time Communication: Socket.io WebSocket server for live updates
- Web Server: Express.js server for HTTP API and static content
- State Management: In-memory game session tracking with live synchronization
- Configurable Difficulty: Scalable scramble complexity from beginner to expert levels
The server follows the recursive MCP pattern:
1. Start → Returns nextAction: 'manipulateCube'
2. Manipulate → Returns nextAction: 'manipulateCube' (if not solved) or 'finish' (if solved)
3. Finish → Returns nextAction: null (workflow complete)
This allows AI agents to work autonomously through the solving process.
`bash`
npm run dev
`bash`
npm run build
`text``
src/
├── app.ts # Main MCP server setup
├── cubeLogic.ts # Rubik's Cube simulation logic
├── visualizationServer.ts # Web visualization server
└── types.ts # TypeScript interfaces
MIT License - see LICENSE file for details.
- Developer Guide: Comprehensive guide covering project architecture, tech stack, and best practices
- Refactoring Plans: Detailed plans for MCP UI integration and difficulty customization
- Extension Roadmap: Future enhancements including web-based game management
For detailed information about MCP UI integration, development workflows, and extending the server functionality, please refer to the additional documentation files.