Rubik's Cube MCP Server

A Model Context Protocol (MCP) server that provides AI agents with the ability to solve Rubik's Cube puzzles 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)
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)

Returns:

Game ID for the session
Initial cube state
Visualization URL
Next action guidance

2. `manipulateCube`

Execute a move on the Rubik's Cube.

Parameters:

gameId (string): The game session ID
move (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

3. `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"
→ startCube tool called
→ Returns scrambled cube state and gameId

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

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

Architecture

MCP Protocol: Standard Model Context Protocol for AI agent communication
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

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

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

Linear MCP Server
ibraheem4
A
security
A
license
A
quality
Enables AI agents to manage issues, projects, and teams on the Linear platform programmatically.
Last updated -
7
83
JavaScript
MIT License
Crew AI MCP Server
MatthewLaw1
-
security
F
license
-
quality
Enables AI agent and task management using the CrewAI framework, allowing users to create and run agents and tasks in an automated workflow environment.
Last updated -
0
3
JavaScript
MCP Think Tank
flight505
A
security
A
license
A
quality
Provides AI assistants with enhanced reasoning capabilities through structured thinking, persistent knowledge graph memory, and intelligent tool orchestration for complex problem-solving.
Last updated -
20
756
29
TypeScript
MIT License
XiaoZhi MCP Aggregate
avxxoo
-
security
F
license
-
quality
A powerful interface for extending AI capabilities through remote control, calculations, email operations, knowledge search, and more.
Last updated -
35
Python

View all related MCP servers

Rubik's Cube MCP Server