Chess Esca

chess-esca-mcp

An MCP server over esca: the rules of chess as JSON an agent can read.

FEN and moves go in; enums and the squares behind them come out. Whether a move is legal and why not, what a position's status is and what either side may claim, the named facts of the position, the ending the material makes and what theory says it is, the opening's ECO code, the moves an opening book holds, and PGN read and written. Every categorical answer also carries prose: the same thing in one plain English sentence, beside the enum rather than instead of it.

There is no engine here and no search. Nothing this server answers says how good a move is. For a number and a line, use chess-uci-mcp, which drives Stockfish or Leela; the two answer different questions and sit well side by side.

Dependencies

Python 3.12 or newer, and uv/uvx.

Usage

"mcpServers": {
  "chess-esca-mcp": {
    "command": "uvx",
    "args": ["chess-esca-mcp@latest"]
  }
}

For Claude Desktop that is claude_desktop_config.json, under Settings → Developer → Edit Config:

• macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

For Claude Code, the plugin does the wiring:

/plugin marketplace add AnglerfishChess/plugins
/plugin install chess-esca-mcp@anglerfish-chess

The server takes no arguments. It reads nothing but the position you hand it and, for book_moves, the book file you name.

Tools

Every tool takes the position the same way: fen (the start position when omitted), moves played from it — each written as SAN (Nf3) or as UCI (g1f3) — or a whole game as pgn instead. variant is classic or chess960. Repetition and fifty-move claims are only visible when the moves that led to the position are given, since a FEN does not carry them.

Tool	Answers
position	The whole state: side to move, check and its checkers, game status, automatic and claimable draws with their evidence, legal-move count, opening, material, both castlings of both colours with every obstacle, the en-passant offer, pins and skewers, and the ending where the material makes one.
legal_moves	Every legal move in SAN and UCI, each with its role, victim, promotion, check and static exchange, and grouped as captures, checks, castling, promotions, en passant and quiet.
explain_move	Whether one move is legal. If not, every reason at once, each with the squares it was read off. If so, what it changes, the position after it, and the draws it would open.
facts	The named facts of the position, group by group, every value labelled by name and, where it differs between the sides, by colour. groups selects; placement and maps are left out unless asked for.
ending	The ending the material makes: its signature, its class, what theory says the result is, the technique that gets it, and the pawn race, bishops and opposition it was read off.
opening	The ECO code and name of the position, and the deepest named position the line reached.
book_moves	The moves a Polyglot opening book holds for the position, with their weights.
pgn	A PGN game read into headers, moves, comments, final position, opening and result.
to_pgn	A list of moves written out as a PGN game.

An input that names no position, no move or no game comes back as {"error": {"kind": ..., "message": ..., "hint": ...}} — never a traceback.

One resource, esca://facts-catalogue, lists every fact group and every field it holds, with the type each carries and one sentence of what it means; esca generates it from the fact definitions themselves. One prompt, analyse-position, walks an agent through reading a position with these tools.

Opening books

No book is bundled. book_moves takes the path to a Polyglot .bin file of your own; the format is the common one, so a book written for any engine that reads Polyglot works. esca.polyglot has download(url, path) for fetching one, and a Builder that writes a book from PGN.

Development

The server is a second distribution inside the esca repository: the library at the root, this directory beside it. It takes esca from the crate next door while you work on it, and from PyPI once installed.

git clone https://github.com/AnglerfishChess/esca.git
cd esca/mcp

uv sync --all-groups     # builds the esca extension from ../ and installs it here
uv run --no-sync pytest
uvx ruff check . && uvx ruff format --check . && uvx pyrefly check

Run it from the checkout with uv run chess-esca-mcp.

The version is esca's own: one tag releases the library and this server together, and the esca== pin names that same version.

The MCP registry

registry.modelcontextprotocol.io is the index of public MCP servers. The listing is described by server.json, under the name io.github.AnglerfishChess/chess-esca-mcp; ownership of the PyPI package is proven by the mcp-name: marker near the top of this file, which becomes the package description PyPI serves. The registry reads it from the published artifact, so it counts only once a release carrying it reaches PyPI.

Related projects

• esca — the library this serves.
• chess-uci-mcp — the engine side: analysis and best moves from Stockfish or Leela.

License

MIT — see LICENSE.