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.
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
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.
- esca — the library this serves.
- chess-uci-mcp — the engine side: analysis
and best moves from Stockfish or Leela.
License
MIT — see LICENSE.