Chess MCP: analysing your games inside a conversation with an AI agent

Short answer

An MCP server declares tools your AI agent can call mid-conversation: evaluate a position, walk a game move by move, explain why a move loses, turn that mistake into a puzzle, and aggregate recent games into an error profile. This guide covers what each of those returns, the centipawn ruler behind the word blunder, what each one costs in seconds on an ordinary machine, and where the tool stops — because it answers now and accumulates nothing.

The essentials in a few lines

• MCP is an open protocol: the server declares tools with a description and an output schema, and the client offers them to the model — the agent calls what it needs instead of you opening a screen.
• Classification comes from the centipawn drop for the side that moved: under 50 is normal, 50 to 99 an inaccuracy, 100 to 199 a mistake, 200 or more a blunder.
• A move that allows mate shows a loss near 100000 centipawns, because mate is worth ±100000 on that scale — the number is the mate, not a count of material.
• Tactical motifs are read off the board from the engine's refutation, and when no rule matches the answer says «unclassified» rather than inventing a name.
• On an eight-core Ryzen 7, evaluating a position at depth 18 took 1.5s, explaining one move 0.5s, and walking a 58-half-move blitz game 3.9s.

What joins the conversation

MCP stands for Model Context Protocol, an open protocol for connecting a language model to outside tools. The server declares each tool with a name, a description and the exact shape of its answer; the client — Claude Desktop, Claude Code, Cursor — shows that list to the model, which decides when to call what. There is no browser in the middle: the server runs as a process on your machine and talks over standard input and output.

The difference shows up on the second question. An analysis site answers one thing per screen: here is the graph, here is the move list. With the tools inside the conversation, the sequence «analyse this game», «why is move 23 a mistake», «build me a puzzle from it» happens without interruption, and every answer is data the agent can cross with the previous one rather than a picture it would have to interpret.

What does not change is the evaluation. Stockfish still does the calculating, at the same strength it would have anywhere else, and the classification uses the same centipawn ruler described in our guide on what the engine means by «blunder». What changes is the distance between the question and the number — and that distance is usually what decides whether analysis turns into study or into a closed tab.

The seven questions the server answers

The diagnostic tool exists for a practical reason: the engine is not bundled. Stockfish is GPL software shipped as a binary per architecture, and you install it yourself. When it is missing, the right answer is not a stack trace but the install command for your system — `brew install stockfish` on macOS, `sudo apt install stockfish` on Debian and Ubuntu, `winget install Stockfish.Stockfish` on Windows.

The four middle tools form a ladder of granularity. Evaluating a position answers «who is better and why» with the engine's top lines. Walking the game returns, for every move, the evaluation before and after, the loss, the classification, the move the engine preferred and the phase. Explaining one move zooms in, with the refutation line and the tactical motifs. Generating puzzles closes the loop, lifting from the game the position immediately before each mistake.

The last two depend on Lichess. The import fetches an account's public games — no login, no token, because the endpoint is public — and returns each PGN alongside time control, colour, result and opening. The profile analyses that batch and aggregates only the moves of the player being profiled, never the opponent's.

From the label to the motif

The arithmetic never changes: loss is the evaluation of the best move before, minus the evaluation after the move played, from the point of view of whoever moved. Under 50 centipawns the move is normal; 50 to 99 an inaccuracy; 100 to 199 a mistake; 200 upwards a blunder. Two labels need more than the loss: `great` requires the second-best move to be at least 150 centipawns behind, and `brilliant` requires a sacrifice of at least 200 centipawns of material that works — both only apply while the position is still undecided.

Mate enters the scale worth ±100000 centipawns, which is why the diagram below produces a loss of 100034 centipawns: the 34 is the evaluation of the position before the move, and the 100000 is the mate. That number is not a material count — it is the distance between a playable position and mate. Worth knowing before reading the output, because an agent that reads 100034 as «a thousand pawns» will write a meaningless sentence from a correct number.

In that same example, measured at depth 18, the engine prefers 3...g6, and the second-best move, 3...Qe7, sits only 24 centipawns behind. That detail changes the lesson: there was no single move to find, there were two comfortable ways out, and the one played was neither. The motifs themselves come from seven rules read off the board — hanging piece, fork, pin, skewer, discovered attack, mate and back rank. When none matches, the answer says «unclassified», which is more honest than calling a fork what was merely a badly placed piece.

The mistake becomes a puzzle

What separates a useful puzzle from a list of better moves is the stopping rule. An engine's principal variation carries on as long as there are moves; if the solution were the whole variation, the puzzle would ask you to guess choices the opponent is not obliged to make. Cutting the line where the reply stops being unique keeps the puzzle with one right answer — the only way it can be marked at all.

In the diagram above, the puzzle presents the position after 3.Qh5, asks Black to move and accepts 3...g6. It does not come from a curated tactics collection: it comes from the game where the mistake happened, and that changes what it trains. A collection puzzle teaches a pattern; a puzzle taken from your own mistake teaches the pattern you have already shown you do not see.

A caveat about where puzzle material comes from. Ready-made tactics collections circulate with labels that do not hold up — some «pins» have a quiet move as their solution, and some «skewers» are mate in one. When the position comes from your own game and the solution comes from the engine running on that position, that class of error has no way in.

The profile: what one game cannot answer

ACPL is the average of those losses with each evaluation capped at plus or minus 1000 centipawns before the subtraction. Without that cap, one queen dropped in an already decided game would flatten the average of twenty games and the number would stop describing your play. It is a triage metric: it compares your own phases with one another, not one player with another.

The phase comes from the position, not from the move number. It is an endgame when non-pawn material on both sides adds up to 26 points or less, counting knight and bishop as 3, rook as 5 and queen as 9; it is the opening while the half-move count is inside the recognised book, or inside the first 16 half-moves, whichever is longer; everything else is the middlegame. An endgame is an endgame on move twelve if the pieces are already off.

Every pattern arrives with its threshold beside it — «78% of blunders in the endgame, threshold 40%». Without that number, «you blunder in the endgame» reads the same at 41% and at 95%, and becomes a horoscope. For the same reason the «unclassified» motif bucket is counted but never promoted to a conclusion: telling someone their recurring motif is «unclassified» hands the question back as an answer.

• ACPL overall and per phase, with the move count of each phase beside it — under ten moves in a phase, the average is not a conclusion.
• Counts per tactical motif and per time control, separating a chess problem from a clock problem.
• The five worst moments, each with the position before the move, what was played and what the engine preferred.
• Patterns declared only above an explicit threshold: 40% of blunders in one phase, 30% of mistakes sharing one motif.

What runs where, and what it costs

Numbers measured on an eight-core Ryzen 7 give the order of magnitude: 1.5 seconds to evaluate a position at depth 18 with three lines; 0.5 seconds to explain a move; 3.9 seconds to walk a 58-half-move blitz game at depth 14; 7.9 seconds for the profile of three games, covering 119 of the player's moves. Twenty games fit inside the five-minute ceiling comfortably on a machine of that size, and on a smaller one the ceiling is what keeps the conversation from stalling.

Each tool states its budget in its own description, and the answer repeats the budget it actually applied. That exists because an agent that asks for depth 30 and silently receives 18 will conclude, correctly, that the analysis is wrong. Asking for more than the ceiling does not return an error: the request is trimmed, and the answer says by how much.

It is worth being precise about where things happen, because these are two different products. In the MCP server, Stockfish is a process the server starts on your machine, and the positions you analyse go to that process; the conversation with Lichess is one request at a time, identified in the header, with a 60-second wait whenever Lichess asks us to slow down. PersonalChess, the web product, is a separate service with its own servers, and that is where the analysis of imported games runs. The MCP package does not talk to it and works with no account at all.

Frequently asked questions