♟️ 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 |
|---|---|
createGame |
Initializes a new chess game session against Computer or another Agent. |
joinGame |
Joins an existing game using its Game ID. |
finishTurn |
Submits a move in UCI format and optionally claims a win. |
waitForNextTurn |
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:
pip install chess-mcp-server
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):
{
"mcpServers": {
"chess": {
"command": "uvx",
"args": ["chess-mcp-server"]
}
}
}
Alternatively, using pip installation:
{
"mcpServers": {
"chess": {
"command": "python",
"args": ["-m", "src.mcp_server"]
}
}
}
🛠️ 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.
- The Agent calls
- 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file chess_mcp_server-0.1.17.tar.gz.
File metadata
- Download URL: chess_mcp_server-0.1.17.tar.gz
- Upload date:
- Size: 127.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
647706b740733706e46992aedebfaff66f9aa8d329e07af2283b6799cd7bb305
|
|
| MD5 |
1b236a73e839b9f67f35a8e47c5a4272
|
|
| BLAKE2b-256 |
59788bb1bf63f4dd173587c43b4583972a34a95577c9587b006ea55e2681946f
|
Provenance
The following attestation bundles were made for chess_mcp_server-0.1.17.tar.gz:
Publisher:
publish.yml on fritzprix/chess-mcp-server
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
chess_mcp_server-0.1.17.tar.gz -
Subject digest:
647706b740733706e46992aedebfaff66f9aa8d329e07af2283b6799cd7bb305 - Sigstore transparency entry: 2626616844
- Sigstore integration time:
-
Permalink:
fritzprix/chess-mcp-server@fd08556f8e32c70e353fdc2a349ee98b805db973 -
Branch / Tag:
refs/tags/v0.1.17 - Owner: https://github.com/fritzprix
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@fd08556f8e32c70e353fdc2a349ee98b805db973 -
Trigger Event:
release
-
Statement type:
File details
Details for the file chess_mcp_server-0.1.17-py3-none-any.whl.
File metadata
- Download URL: chess_mcp_server-0.1.17-py3-none-any.whl
- Upload date:
- Size: 39.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bd8928dd6a0677c7a6891e27654a5e544bbecb7f00cbc0d06d3f127a689c991e
|
|
| MD5 |
778599576b7b442a2f602ad595049af1
|
|
| BLAKE2b-256 |
192b3b5a7d13f429c50a8bf6c85d9ee55f0973b704c21857bf79861d779e0107
|
Provenance
The following attestation bundles were made for chess_mcp_server-0.1.17-py3-none-any.whl:
Publisher:
publish.yml on fritzprix/chess-mcp-server
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
chess_mcp_server-0.1.17-py3-none-any.whl -
Subject digest:
bd8928dd6a0677c7a6891e27654a5e544bbecb7f00cbc0d06d3f127a689c991e - Sigstore transparency entry: 2626616862
- Sigstore integration time:
-
Permalink:
fritzprix/chess-mcp-server@fd08556f8e32c70e353fdc2a349ee98b805db973 -
Branch / Tag:
refs/tags/v0.1.17 - Owner: https://github.com/fritzprix
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@fd08556f8e32c70e353fdc2a349ee98b805db973 -
Trigger Event:
release
-
Statement type:
