chess-mcp

MCP server that exposes chess analysis tools (Stockfish + Maia2 human move prediction) for use with Claude Desktop, Claude Code, or any MCP-compatible client.

Prerequisites

• Python 3.10+
• Stockfish binary
• CUDA GPU recommended (CPU works but Maia2 inference will be slower)

Quick start

git clone https://github.com/CSSLab/chess-mcp.git
cd chess-mcp
pip install -r requirements.txt

Install Stockfish:

# 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:

# 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:

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)