Pre-release

This release is a pre-release and may not be stable for production use.

♟️ 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 finishTurn to 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.

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chess_mcp_server-0.1.17b3.tar.gz (125.8 kB view details)

Uploaded Aug 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

chess_mcp_server-0.1.17b3-py3-none-any.whl (38.3 kB view details)

Uploaded Aug 28, 2026 Python 3

File details

Details for the file chess_mcp_server-0.1.17b3.tar.gz.

File metadata

Download URL: chess_mcp_server-0.1.17b3.tar.gz
Upload date: Aug 28, 2026
Size: 125.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chess_mcp_server-0.1.17b3.tar.gz
Algorithm	Hash digest
SHA256	`0a7e906618da229aa6246a5e95ac62624b5be795caf6375cdc18e47cef4d4ca1`
MD5	`f21806076cf0c683e3fe284a29ccde63`
BLAKE2b-256	`76f0bcdbb3a071fcd6d5ffc977ada99b646cbd5d037f8dc4ec4eb709f86c7d8c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for chess_mcp_server-0.1.17b3.tar.gz:

Publisher: publish.yml on fritzprix/chess-mcp-server

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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.17b3.tar.gz
- Subject digest: 0a7e906618da229aa6246a5e95ac62624b5be795caf6375cdc18e47cef4d4ca1
- Sigstore transparency entry: 2625455624
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: fritzprix/chess-mcp-server@62a43103da70e8fc0f50a3983624805b1998a785
- Branch / Tag: refs/tags/v0.1.17b3
- Owner: https://github.com/fritzprix
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@62a43103da70e8fc0f50a3983624805b1998a785
- Trigger Event: release