chess-coach
Allows syncing a player's public chess.com games via the chess.com public API monthly archives, then analyzing them with Stockfish to produce coaching reports, mistake breakdowns, trends, and practice recommendations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chess-coach Why am I not winning my blitz games, and what should I practise this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
chess-coach
Why am I not winning more of my chess.com games, and what should I practise this week?
chess-coach downloads a player's chess.com games, checks every move with Stockfish, and serves the results as MCP tools. An LLM client such as Claude can then answer that question from the player's own games, with sample sizes attached. The numbers come from code; the model only puts them into words.
Two-pass analysis (depth 12, re-checked at depth 16 on costly moves) recovers ~94% of the blunders a depth-20 search finds. A flat depth-20 search took 90 s per blitz game in the depth benchmark. The two-pass analysis takes a median of 10.4 s per game in production. Those two timings come from different games and engine settings, so no ratio is given (evidence).
Example
"Why am I not winning my blitz games?" → the client calls
coach_plan(username, time_class="blitz")
Real output from my last 100 blitz games, trimmed (game links removed):
{
"games_not_won": 59,
"why_games_were_not_won": {
"thrown_win": {"games": 33, "share_of_non_wins": 0.56, "meaning": "had a winning position and did not win"},
"blunder": {"games": 12, "share_of_non_wins": 0.2, "meaning": "one costly mistake decided it"},
"time": {"games": 8, "share_of_non_wins": 0.14, "meaning": "lost on the clock while the position was not clearly lost"},
"opening": {"games": 6, "share_of_non_wins": 0.1, "meaning": "was already clearly worse after the opening"}
},
"weekly_focus": {
"area": "thrown_win",
"because": "33 of 59 recent games that were not won (had a winning position and did not win)."
},
"trend_vs_earlier_games": {
"score_pct": {"recent": 42.0, "before": 52.2, "change": -10.2, "noise_margin": 10.1, "verdict": "worse"}
},
"commentary": {
"backend": "template",
"text": "33 of your 59 recent games that were not won started from a winning position. Across 414 such games in your history, the opponent's very next move won material or mated after 45% of your decisive blunders, and in 92% you still had plenty of time: the pattern points at a checking habit rather than at speed. ...",
"faithfulness": {"ok": true, "unsupported_numbers": []}
}
}Related MCP server: Chess Engine MCP Server
What it does
Why am I losing? Assigns each game that was not won one main cause (thrown win, single blunder, bad opening, clock, gradual decline), picks one focus for the week, and compares recent games with earlier ones. A change is only called real when it is larger than the noise margin.
Which mistakes do I repeat? Grades every move by how much win chance it lost. Mistakes and blunders get a tag for what went wrong (piece left hanging, missed capture/check/mate, allowed fork, pin or discovered attack, ignored threat). It also lists the costliest moments and the wins the player let slip.
Where and when do I play badly? Breaks results down by opening, game phase, clock pressure, time of day, and play after a loss (tilt). It also measures how often the player saves bad positions.
How do I compare with players at my level? Puts the player's 3+0 blitz numbers next to rating-band medians and quartiles measured on public games.
Show me the game. Returns any cached game move by move with evaluations, best lines, clock times and tags. A local web dashboard adds a board viewer and exercises built from the player's own mistakes.
Architecture
flowchart LR
A[chess.com public API<br/>monthly game archives] -->|sync_games<br/>skips games already stored| B[(SQLite cache<br/>games)]
B --> C[Stockfish two-pass analysis<br/>depth 12 every position<br/>depth 16 on costly moves]
C --> D[(SQLite<br/>positions, mates, best lines)]
D --> E[Motif tagging<br/>python-chess rules over stored lines]
E --> D
D --> F[Reports<br/>causes, trends, openings, clock,<br/>tilt, peers, motifs]
P[benchmarks.json<br/>rating-band aggregates] --> F
F --> G[MCP server<br/>FastMCP, stdio, 20 tools]
G --> H[LLM client<br/>Claude Desktop / Claude Code]
F --> W[Local web dashboard<br/>127.0.0.1 only]Knowledge layer
coach_plan attaches short practice advice to the weekly focus. On my machine that
advice comes from principles written from chess-training books. That full set is kept private for
copyright reasons. This repository ships the code, the schema, a bibliography (titles and
authors) and five example principles. The examples are written in original
wording. When the private set is absent, the code loads the examples.
Key engineering decisions
1. Two-pass engine analysis instead of a flat deep search.
Decision: search every position at depth 12, then search again at depth 16 only for the two positions around any move that lost 80 cp or more at depth 12 (analysis.py).
Alternatives: flat depth 20 (the reference), or a flat depth of 14 to 18.
Why: a flat depth 20 took 90 s per blitz game on one 4-thread engine. Depth 12 took 2.1 s but found only 83% of the depth-20 blunders.
Evidence: on 12 games / 865 positions, docs/evidence/depth_benchmark.txt measured blunder recall and seconds per game for depths 6 to 20. Compared with a depth-20 search of the same moves, the two-pass result recovered 94.2% of blunders at 90.3% precision (940 moves, about 800 rating) (two_pass_validation_800.txt). On stronger players it recovered 94.4% at 94.4% precision (721 moves, 1500 to 2300 rating) (two_pass_validation_1500-2300.txt).
Not tuned yet: the 80 cp cut-off and the depth-16 second pass were chosen by judgement, not by a parameter sweep (#6).
2. Grade moves by lost win chance, not raw centipawns.
Decision: convert evaluations to win chance with Lichess' published logistic fit. Lost win-chance points set the grade: inaccuracy 5, mistake 10, blunder 15 (classify.py).
Alternative: fixed centipawn cut-offs (100/200 cp).
Why: losing 200 cp from an equal position decides a game. Losing 200 cp when already up +900 changes nothing.
Evidence: the rationale is written in
classify.py.Not tuned yet: the 5/10/15 win-chance thresholds were chosen by judgement and have not been tested against any reference (same issue, #6).
3. Facts come from code, words from a replaceable commentator, and the text is checked.
Decision: reports return structured facts. Prose comes from a
Commentatorinterface. Every number in the generated text is checked against the facts, and unfaithful text is replaced by the template output (commentary.py).Alternative: let the LLM read raw evaluations and write the coaching itself.
Why: a coaching claim is only useful if it is true of the player's games.
Evidence: tests in
tests/test_commentary.py.Not done yet: only the template backend exists, so no LLM backend has been through this check.
4. Peer comparison from public games, aggregates only, same clock.
Decision: scripts/find_peers.py samples active public players (country lists TR/IS/LT, plus CM/NM title lists for the top band, rating deviation ≤ 90, played blitz in the last 45 days) into four blitz bands. scripts/build_benchmarks.py runs them through the same analysis pipeline and writes only band medians and quartiles to benchmarks.json. No usernames or games are kept in the file.
Alternative: compare against chess.com's published averages (no per-metric data), or keep per-player rows.
Why: a fair comparison needs the same metric code on the same time control (3+0 only), and publishing other players' data is not acceptable.
Evidence: 14 to 17 players per band, 30 games each. A band built from fewer than 8 players is marked tentative and the tool gives no verdict for it (peers.py).
5. Every comparison carries its noise margin.
Decision: rates are compared with a 95% noise margin, and rates built from moves use per-game values. Moves inside one game are not independent, so the honest sample size is the number of games (stats.py). Each side needs at least 10 observations before a difference can be called clear.
Alternative: report raw differences.
Why: with tens of games per window, a 10-point swing in score can be luck. In the example above the swing is −10.2 against a margin of 10.1.
Numbers
All numbers come from my local database or from the files in docs/evidence.
Games cached | 3,104 (Dec 2025 – Oct 2026; blitz 1,265, bullet 1,075, rapid 762, daily 2) |
Games analysed | 2,800 (90.2%); 304 pending |
Positions stored | 165,765 |
Costly moves tagged with a motif | 12,677 in 2,799 games; 57.6% match no rule ( |
Engine time per game, two-pass (production) | median 10.4 s, mean 13.7 s over 2,800 games (Stockfish 19, 2 threads/engine, up to 4 engines in parallel) |
Engine time per game, flat depth (benchmark, 1 engine, 4 threads) | depth 12: 2.1 s · 14: 9.8 s · 16: 27.3 s · 18: 48.0 s · 20: 90.0 s |
Quickstart sample (fresh clone, 16 logical CPUs) | 30 games analysed in 132 s wall clock |
Peer benchmark | 4 rating bands, 14–17 players each, 30 games of 3+0 blitz per player |
Tests | 197 passed, 4 skipped as cloned (the skipped ones need the private principle set); 201 passed with it |
All timings were measured on a Ryzen 9 7940HS.
Quickstart
Requires Python 3.11+ and a Stockfish binary. Stockfish is GPL-licensed and is not included in this repository.
git clone https://github.com/m-allakov/chess-coach.git
cd chess-coach
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -qPoint the code at a database and at Stockfish. The variables are listed in .env.example. The code reads them from the environment and does not load the file itself.
export CHESS_COACH_DB=./.data/games.db
export CHESS_COACH_STOCKFISH=/path/to/stockfishTry it offline with the sample (30 anonymized 3+0 blitz games, player sample_player):
python examples/load_sample.py
python -m chess_coach.cli analyze sample_player
python -m chess_coach.cli tag sample_playerOr use your own games (chess.com public API, no account or key needed):
python -m chess_coach.cli sync <your_chess_com_username> --months 3
python -m chess_coach.cli analyze <your_chess_com_username>
python -m chess_coach.cli tag <your_chess_com_username>Connect an MCP client. For example, in Claude Desktop's claude_desktop_config.json or in a
project .mcp.json for Claude Code:
{
"mcpServers": {
"chess-coach": {
"command": "/absolute/path/to/chess-coach/.venv/bin/chess-coach-mcp",
"env": {
"CHESS_COACH_DB": "/absolute/path/to/chess-coach/.data/games.db",
"CHESS_COACH_STOCKFISH": "/path/to/stockfish"
}
}
}
}Then ask: "Use coach_plan for sample_player. Why are the games not being won?"
Optional dashboard: chess-coach-web --username sample_player, then open http://127.0.0.1:8765.
MCP tool reference
Question | Tool | What it returns |
Get my data in |
| Downloads the last N monthly archives (standard chess only) and skips games already stored |
| Two-pass Stockfish analysis of pending games, newest first, in time-boxed batches; also tags motifs | |
| Tags mistakes and blunders with the kind of error | |
| Adds mate scores and best lines to games analysed before those were stored | |
| Games cached / analysed / pending | |
Why am I not winning? |
| Start here. One cause per game not won, a weekly focus with evidence, sourced advice, a trend with noise margin |
| Losses by phase, colour and time control; winning positions thrown away | |
| Games that reached a winning position and were not won: the move where it collapsed, its clock, its tags | |
Which mistakes do I repeat? |
| Count, share and average win-chance loss per motif, split by phase, pace and colour, with examples |
| Costliest confirmed blunders with FEN, move played, best move | |
| How often the player punished opponent blunders; missed forced mates | |
| Sound piece offers (a rough stand-in for chess.com's "brilliant"; see Limitations) | |
Where and when do I play badly? |
| Results and opening-phase quality per opening and colour |
| Errors by clock zone, hasty vs considered blunders, losses on time | |
| Play after losses and late in a session | |
| Results and blunder rate by hour and weekday/weekend | |
| How often clearly worse positions were saved | |
How do I compare? |
| 3+0 blitz metrics next to four rating bands (p25 / median / p75) |
Show me a game |
| Cached games with filters, to find a |
| One game move by move: evals, win chances, grade, best line, clock, motifs |
Limitations and roadmap
No one has checked whether the coaching advice is correct. The faithfulness check confirms that numbers in the text match the computed facts. It does not test whether the advice is right for the player. Next: an LLM-based evaluation of coaching output against engine ground truth.
Local only. The MCP server runs over stdio and the dashboard listens on 127.0.0.1. A web deployment is planned.
Motif rules explain a minority of costly moves. 57.6% of tagged moves match no rule.
"Brilliant" detection did not work. A rule tested against chess.com's own labels found 38 of 39 brilliant moves at 9.4% precision (brilliant_onlymove.txt).
sacrifice_candidatestherefore says it over-reports.Small peer samples. 14 to 17 players per band, drawn from three countries and two title lists, 3+0 blitz only.
Sync downloads the last N months again on every run. Duplicates are skipped by game URL. It makes no conditional requests and has no retry or back-off for rate limits.
The trend compares recent games against all earlier games, including much older and lower-rated ones. No opening-book detection exists.
Only the template commentary backend exists. The coach agent described in docs/PROJECT_PLAN.md is not built.
How it was built
Built with AI-assisted development (Claude Code). I owned problem framing, architecture, analysis decisions and verification.
License
MIT, see LICENSE. Stockfish is not distributed with this project.
Available Tools
20 toolsanalysis_statusB
How many of a player's cached games are analysed vs pending.
Inputs: username (required).
analyze_gamesA
Analyse not-yet-analysed games with Stockfish, newest first, and tag their costly moves with motifs (see tag_motifs).
Works in small batches so one call stays fast; call again to continue. Returns progress counts only. Use sync_games first to download games.
Inputs: username (required), batch_size, max_seconds.
backfill_game_detailsA
Add mate scores and best-line (PV) data to games analysed before they were stored, so get_game can show them. Re-searches only costly moves and near-decided positions; stored evaluations never change. Works in batches: call again until backfill_pending is 0.
Inputs: username (required), batch_size, max_seconds.
coach_planB
Start here. Why the player's recent games were not won (one primary cause each), one focus for the coming week with the evidence, and the trend against earlier games. Use the other reports to drill into the focus area.
Inputs: username (required), time_class, recent_games.
conversion_reportC
Games where the player reached a winning position (win chance >= threshold, counted as weakness_report counts it) and did not win: how often, how they ended, which move collapsed the position (phase, clock, motif tags), when the win chance fell below 50 for good, and the newest n such games with the details. collapse_type is single, time, gradual or other.
Inputs: username (required), n, color, last_n, +2 more.
get_gameA
One cached game move by move, from the stored analysis (no engine is run).
game is a game_id or a chess.com game link. Pass username so meta.my_color is set.
ply_from/ply_to are an inclusive range. only_flagged keeps just inaccuracies, mistakes and
blunders of either side, plus the ply before and after each (marked "context": true).
Conventions:
ply 1 is White's first move, ply 2 Black's first; Black's n-th move is ply 2n.
eval_before/eval_after are always from WHITE's point of view: {"cp", "mate"}. cp is clipped to +-1000. When a mate is known, cp is null and mate is the number of moves (positive = White mates). mate 0 = the position is checkmate ("mated" names the loser).
win_chance_before/after and wp_loss (0-100 scale) are from the point of view of the side that MADE the move, the same as worst_moments. class is best/good/inaccuracy/mistake/ blunder, using the same thresholds as the reports. No opening-book detection exists.
Every win chance, loss and percentage in every tool is rounded to 1 decimal, halves up, so the same move reads the same everywhere. Classes use the unrounded value.
mate_before_mover: N when the mover had a forced mate in N before moving. missed_mate: N when the move left no mate for the mover (class is NOT changed by this, a missed mate can still read "good"). mate_lengthened: {"from": N, "to": M} when a mate survives but takes more than N-1 moves. All null when there was no mate or the mate data is unknown (see meta.mate_data and the note). only_flagged also keeps a missed mate of 5 moves or fewer.
motifs: why a costly move (mistake, blunder, or a mate of 5 moves or fewer let go) was costly, e.g. ["moved_piece_hangs"], ["untagged"] when no rule fits. [] = not costly enough to tag; null = costly but not tagged yet (run tag_motifs). motif_details carries extras such as {"allowed_fork": {"with_check": true}}.
best_san/best_uci are null when the move played was the engine's best; best_pv_san (up to 5 plies, starts with the best move) is still given, or null if not stored.
clock_after is seconds left after the move; time_spent includes the increment. Both are null when the game has no clock data.
An unanalysed game returns SAN/UCI/FEN/clock with all evaluation fields null.
Inputs: game (required), ply_to, ply_from, username, +2 more.
list_gamesA
The player's cached games, newest first, to find a game_id for get_game.
Filters: time_class (bullet/blitz/rapid), color ("white"/"black"), result from the player's side ("win"/"loss"/"draw"), opening (case-insensitive substring of the name). Each game has game_id, url, end_time (ISO 8601, UTC), time_control, time_class, color, opponent, opponent_rating, my_rating, result, termination, eco, opening, moves_count (full moves) and analyzed.
Inputs: username (required), n, color, result, +2 more.
missed_opportunitiesC
How often the player used the opponent's blunders, and the costliest chances missed.
missed_mates lists forced mates the player had and let go: shortest mate first, then newest.
Inputs: username (required), n, last_n, time_class.
motif_reportB
What kinds of costly moves the player makes: counts, share and average win-chance loss per motif tag, split by phase, pace (hasty / considered / short of time) and colour, plus the newest and costliest examples of each. A move can carry several tags, so shares can add up to more than 100%; untagged_share_pct is the part no rule explains. min_class is "mistake" or "blunder". pending_moves counts costly moves in games not tagged yet (run tag_motifs).
Inputs: username (required), color, phase, last_n, +3 more.
opening_reportC
Results and opening-phase quality per opening and colour, worst first.
Inputs: username (required), last_n, min_games, time_class.
peer_comparisonA
Compare the player's 3+0 blitz numbers with players of other rating bands (medians and quartiles from public games). Sample sizes are listed per band; thin bands are flagged tentative and give no verdict.
Inputs: username (required).
resilience_reportC
How often the player saved (won or drew) a game after a clearly worse position.
Inputs: username (required), time_class.
sacrifice_candidatesB
Sound moves that put a piece on offer. Approximates chess.com's 'brilliant' label but over-reports (about ten false candidates per real brilliant).
Inputs: username (required), n, last_n, time_class.
sync_gamesA
Download a chess.com player's recent games into the local cache.
Only standard chess is stored. Already-cached games are skipped, so it is safe to call repeatedly. Returns counts, not the games themselves.
Inputs: username (required), months.
tag_motifsA
Tag the costly moves (mistakes, blunders, short mates let go) of analysed games with the kind of error they are: moved_piece_hangs, left_piece_hanging, missed_capture, missed_check, missed_mate, allowed_fork, allowed_discovered_attack, allowed_pin_or_skewer, ignored_threat, or untagged. Newest games first, in batches; call again until motif_pending is 0. Reads the stored analysis; Stockfish is asked only for a ply whose line was never stored, once, at a fixed depth (engine_searches says how many).
Inputs: username (required), batch_size, max_seconds.
tilt_reportB
Does the player play worse after losses, or later in a session? Games are grouped into sessions (a pause longer than the gap starts a new one). Differences are reported only when they are larger than sampling noise.
Inputs: username (required), time_class, session_gap_minutes.
time_of_day_reportC
Results and blunder rate by time of day (local clock) and weekday vs weekend.
Inputs: username (required), time_class.
time_pressure_reportC
How the clock affects a player's results: errors by time-pressure zone, hasty vs considered blunders, time spent per phase, and games lost on time.
Inputs: username (required), last_n, time_class.
weakness_reportA
Where a player loses most: by game phase, colour and time control, and how often winning positions are thrown away. Optionally limit to a time class (bullet/blitz/rapid) and/or the most recent N analysed games.
Inputs: username (required), last_n, time_class.
worst_momentsC
The player's costliest confirmed blunders with FEN, move played and best move.
Inputs: username (required), n, last_n, time_class.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Many report tools overlap in purpose: weakness_report, motif_report, time_pressure_report, conversion_report, resilience_report, tilt_report, and worst_moments all diagnose why the player loses or where errors concentrate. Descriptions do carve out distinct dimensions, but an agent must read carefully to choose the right report, and several share the same underlying evidence.
All names use snake_case, with a fairly predictable split between action tools (sync_games, analyze_games, tag_motifs, backfill_game_details) and noun_report tools. Minor deviations like analysis_status, worst_moments, coach_plan, and sacrifice_candidates keep it from being perfectly uniform.
Twenty tools is heavy for a chess-coaching server. Each report has a defensible purpose, but several could reasonably be consolidated, and the large analytical surface increases selection burden.
The surface covers the full lifecycle: syncing games, analysing with Stockfish, tagging motifs, backfilling details, inspecting individual games, status checks, and a broad set of reports leading into a coach_plan. No obvious operational gap remains for the stated coaching purpose.
Maintenance
Related MCP Connectors
Review your Chess.com and Lichess games with Stockfish on an interactive board, in plain words.
Chess ratings explained, an Elo calculator, and any Chess.com or Lichess player's recent games.
Pedagogical chess intelligence for AI agents: explain positions and games for a target Elo.
Chess tools: game reviews for Chess.com and Lichess, FIDE ratings, openings, positions, puzzles.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to explore player profiles, ratings, game archives, leaderboards, clubs, and puzzles via the Chess.com API.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to perform professional-grade chess analysis using Stockfish and optionally Leela Chess Zero, including position analysis, full game review, opening lookup, and puzzle generation.12 npm2MIT
- AlicenseAqualityCmaintenanceEnables querying Chess.com public data including player profiles, stats, games, and club information through natural language.9MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query Chess.com's public API for player profiles, stats, game archives, online status, clubs, and titled players, and to download game PGNs.MIT