This Chess MCP Server enables AI agents and LLMs to play chess interactively, providing game management, move execution, and real-time board visualization through the Model Context Protocol.
Create and manage chess games: Initialize games against computer AI (difficulty levels 1-10, from "Random Blunderer" to "Minimax Master") or other agents, specifying player color and UI preferences with automatic Game ID generation.
Join existing games: Connect to ongoing games using Game IDs to participate as a player.
Execute moves and turn-based gameplay: Submit moves in UCI format (e.g., e2e4), claim checkmate/win conditions, and use long-polling to wait for opponent moves (up to 30 seconds) with automatic timeout handling.
Real-time board visualization: View boards in Markdown format for text-based analysis or interactive HTML with drag-and-drop piece movement (when
showUiis enabled in supported MCP clients).Monitor via web dashboard: Access
http://localhost:8080to view all active games and spectator views.Flexible game modes: Support Human vs Computer, Agent vs Computer, Agent vs Agent, and Human vs Agent gameplay.
Tools API:
createGame(initialize sessions),joinGame(connect to existing games),finishTurn(submit moves), andwaitForNextTurn(receive opponent moves).Spatial understanding: Provide chess board context enabling LLMs to understand positions, legal moves, and strategic relationships between pieces.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Chess MCP ServerStart a new chess game against you at level 5. You go first."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
♟️ Chess MCP Server
Give your AI Agent eyes to see the board and hands to make the move.
This is not just a chess API. It's a Model Context Protocol (MCP) server designed to let Large Language Models (LLMs) like Claude play chess agentically.
Capable of visualizing the board in real-time HTML, understanding spatial relationships via Markdown, and challenging you with a hybrid difficulty engine (Levels 1-10)—or simply facilitating a game between you and your Agent.
🚀 Features
MCP-UI Support: Interactive HTML board embedded directly in the chat (where supported).
Hybrid AI Engine: Adjustable difficulty from "Random Blunderer" (Level 1) to "Minimax Master" (Level 10).
Agent vs. Agent: Let two AI personalities battle it out.
Web Dashboard: Automatically launches a local sidecar dashboard (
http://localhost:8080) to monitor all active games.
🧰 Tools API
Tool | Description |
| Initializes a new chess game session against Computer or another Agent. |
| Joins an existing game using its Game ID. |
| Submits a move (algebraic or UCI) and optionally claims a win. |
| Long-polling tool that waits for the opponent's move. |
For full specification, see docs/spec/tools.md.
📦 Installation
Prerequisites
Python 3.10+
An MCP Client (e.g., Claude Desktop, Cursor)
1. Installation
You can install directly from PyPI:
2. Configure MCP Client
Add the following to your MCP Client configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Alternatively, using pip installation:
🛠️ Development
If you want to modify the code:
Clone & Setup
git clone https://github.com/fritzprix/chess-mcp-server.git cd chess-mcp-server python -m venv .venv source .venv/bin/activate pip install -e .
🎮 How to Play
Once the server is connected, you can ask your Agent to start a game.
Start a Game
Ask: "Start a new chess game against the computer at level 5."
The Agent calls
createGame.Pro Tip: You can also ask "I want to play against YOU. Create a game where you are White."
Join an Existing Game
If you have a Game ID (e.g., from another agent), you can ask: "Join game [Game_ID]".
The Agent calls
joinGame.
The Game Loop
Your Move:
Interact with the HTML Board if shown. Drag your piece and click Confirm.
Or tell the Agent: "Move pawn to e4."
Agent's Turn:
The Agent calls
waitForNextTurn.It sees the board (Markdown or HTML) and thinks about the move.
It calls
finishTurnto submit its move.
Checkmate:
If you deliver the final blow, you can check the "Claim Checkmate" box on the UI or tell the Agent "Checkmate!".
Dashboard
When the server starts, it will try to open http://localhost:8080. You can view the list of all active games and spectator views there.