Content
# chess-mcp
MCP server that exposes chess analysis tools (Stockfish + [Maia2](https://github.com/CSSLab/maia2) human move prediction) for use with Claude Desktop, Claude Code, or any MCP-compatible client.
## Prerequisites
- Python 3.10+
- [Stockfish](https://stockfishchess.org/download/) binary
- CUDA GPU recommended (CPU works but Maia2 inference will be slower)
## Quick start
```bash
git clone https://github.com/CSSLab/chess-mcp.git
cd chess-mcp
pip install -r requirements.txt
```
Install Stockfish:
```bash
# macOS
brew install stockfish
# Ubuntu / Debian
sudo apt install stockfish
# Windows — download from https://stockfishchess.org/download/
```
Then set the `STOCKFISH_PATH` environment variable to the binary location:
```bash
# macOS (Homebrew)
export STOCKFISH_PATH=$(which stockfish)
# Or specify the path directly
export STOCKFISH_PATH=/usr/local/bin/stockfish
```
## Configuration
The server is configured via environment variables:
| Variable | Description | Default |
|---|---|---|
| `STOCKFISH_PATH` | Path to Stockfish binary | **Required** |
| `STOCKFISH_DEPTH` | Stockfish search depth | `24` |
| `STOCKFISH_TOP_N` | Default number of top Stockfish moves | `3` |
| `MAIA2_TYPE` | Model type: `rapid` or `blitz` | `rapid` |
| `MAIA2_DEVICE` | PyTorch device: `cuda` or `cpu` | `cuda` |
| `MAIA2_TOP_N` | Default number of top Maia2 predictions | `5` |
| `MAIA2_SAVE_ROOT` | Directory for auto-downloaded model weights | `./models` |
Model weights are automatically downloaded on first run via `maia2.model.from_pretrained()`.
## Usage with Claude
Copy `claude_mcp_config.example.json` and edit the paths for your setup.
**Claude Desktop** — add the server entry to your Claude Desktop MCP config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS).
**Claude Code** — add to your project or user settings:
```bash
claude mcp add chess-tools -- python /path/to/chess-mcp/server.py
```
Or add the config from the example JSON to `.claude/settings.json`.
## Available tools
### Board & moves
- **is_move_legal** — check if a move is legal
- **get_legal_moves** — list all legal moves grouped by piece
- **make_move** / **make_moves** — apply move(s) and return resulting FEN
### Notation
- **uci_to_san** / **uci_to_san_batch** — convert UCI to SAN
- **san_to_uci** / **san_to_uci_batch** — convert SAN to UCI
### PGN & FEN
- **pgn_to_fen** — get FEN at any point in a PGN game
- **get_pgn_moves** — extract clean move list from raw PGN
### Board inspection
- **get_piece_at** — identify piece on a square
- **get_game_status** — turn, check, castling, draw conditions
- **board_to_ascii** / **board_to_svg** — render board diagrams
### Analysis
- **evaluate_position** — static evaluation (material, pawns, mobility)
- **find_tactics** — pins, forks, checks, hanging pieces
- **stockfish_analyse** — Stockfish engine analysis with WDL
### Human move prediction (Maia2)
- **predict_human_move** — predict what a player of a given Elo would play
- **predict_human_move_all_levels** — compare predictions across all skill levels (1050–2050)
