The Rubik's Cube MCP Server enables AI agents and users to interactively solve Rubik's cubes through a Model Context Protocol interface with comprehensive game management and visualization features.
Game Management: Initialize new cube sessions with optional scrambling and configurable difficulty (1-100 moves), or join existing games for collaborative solving
Cube Manipulation: Execute standard moves using notation (U, D, L, R, F, B, U', D', L2, etc.) with real-time state tracking
3D Visualization: Access live web interface at
http://localhost:3000
with interactive mouse controls and move history displayAI Integration: Guide agents through solving with step-by-step next action guidance and recursive workflow support
Session Completion: Retrieve final statistics, move history, and completion status with automatic solution detection and celebration effects
MCP UI Features: Interactive web components with clickable game links and visual feedback for enhanced user experience
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
Build the Project
Run the 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
:
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
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/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
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
Building
Project Structure
License
MIT License - see LICENSE file for details.
Additional Documentation
- 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.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI agents to solve Rubik's Cube puzzles through systematic manipulation with standard cube notation moves. Features real-time 3D visualization and interactive controls for tracking solving progress.
Related MCP Servers
- AsecurityAlicenseAqualityEnables AI agents to manage issues, projects, and teams on the Linear platform programmatically.Last updated -783MIT License
- AsecurityAlicenseAqualityProvides AI assistants with enhanced reasoning capabilities through structured thinking, persistent knowledge graph memory, and intelligent tool orchestration for complex problem-solving.Last updated -2032442MIT License
- -securityAlicense-qualityProvides AI-powered search, research, and reasoning capabilities through integration with Perplexity.ai, offering three specialized tools: general conversational AI, deep research with citations, and advanced reasoning.Last updated -1MIT License
- -securityAlicense-qualityEnables AI agents to interact with Unity projects through multimodal vision, code analysis, asset management, and scene manipulation. Supports real-time Unity editor control, project search, script creation, and visual debugging through screenshots.Last updated -25MIT License