Rubik's Cube MCP Server
A 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.
Features
- 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
Installation & Setup
Prerequisites
- Node.js 18.x or higher
- npm or yarn
Install Dependencies
cd rubiks-cube-mcp-server
npm install
Build the Project
npm run build
Run the Server
npx rubiks-cube-mcp-server
This will start both:
- MCP server on stdio (for AI agent communication)
- Web visualization server on
http://localhost:3000
Claude Desktop Configuration
To use this MCP server with Claude Desktop, add the following to your claude_desktop_config.json:
{
"mcpServers": {
"rubiks-cube": {
"command": "npx",
"args": ["rubiks-cube-mcp-server"]
}
}
}
Configuration file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
After adding the configuration, restart Claude Desktop to load the MCP server.
MCP Tools
1. startCube
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
2. joinGame
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
3. manipulateCube
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
4. finish
Complete the Rubik's Cube game session.
Parameters:
gameId(string): The game session ID
Returns:
- Final game statistics
- Move history
- Completion status
Cube Notation
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)
Example Usage with AI Agent
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
Web Visualization
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
MCP UI Features
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
Starting a Game with UI
When you call the startCube tool, you'll receive:
- A clickable UI resource linking directly to the game
- Complete game state data in JSON format
- Metadata including difficulty level and next action guidance
Joining Existing Games
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
Architecture
- MCP Protocol: Standard Model Context Protocol for AI agent communication
- MCP UI Integration: Interactive web components with
@mcp-ui/serverfor 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
Workflow Pattern
The server follows the recursive MCP pattern:
- Start → Returns nextAction: 'manipulateCube'
- Manipulate → Returns nextAction: 'manipulateCube' (if not solved) or 'finish' (if solved)
- Finish → Returns nextAction: null (workflow complete)
This allows AI agents to work autonomously through the solving process.
Development
Watch Mode
npm run dev
Building
npm run build
Project Structure
src/
├── app.ts # Main MCP server setup
├── cubeLogic.ts # Rubik's Cube simulation logic
├── visualizationServer.ts # Web visualization server
└── types.ts # TypeScript interfaces
License
MIT License - see LICENSE file for details.