Skip to main content
Glama

chess-coach

tests

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 Commentator interface. 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 (untagged)

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 -q

Point 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/stockfish

Try 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_player

Or 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

sync_games

Downloads the last N monthly archives (standard chess only) and skips games already stored

analyze_games

Two-pass Stockfish analysis of pending games, newest first, in time-boxed batches; also tags motifs

tag_motifs

Tags mistakes and blunders with the kind of error

backfill_game_details

Adds mate scores and best lines to games analysed before those were stored

analysis_status

Games cached / analysed / pending

Why am I not winning?

coach_plan

Start here. One cause per game not won, a weekly focus with evidence, sourced advice, a trend with noise margin

weakness_report

Losses by phase, colour and time control; winning positions thrown away

conversion_report

Games that reached a winning position and were not won: the move where it collapsed, its clock, its tags

Which mistakes do I repeat?

motif_report

Count, share and average win-chance loss per motif, split by phase, pace and colour, with examples

worst_moments

Costliest confirmed blunders with FEN, move played, best move

missed_opportunities

How often the player punished opponent blunders; missed forced mates

sacrifice_candidates

Sound piece offers (a rough stand-in for chess.com's "brilliant"; see Limitations)

Where and when do I play badly?

opening_report

Results and opening-phase quality per opening and colour

time_pressure_report

Errors by clock zone, hasty vs considered blunders, losses on time

tilt_report

Play after losses and late in a session

time_of_day_report

Results and blunder rate by hour and weekday/weekend

resilience_report

How often clearly worse positions were saved

How do I compare?

peer_comparison

3+0 blitz metrics next to four rating bands (p25 / median / p75)

Show me a game

list_games

Cached games with filters, to find a game_id

get_game

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_candidates therefore 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 tools
analysis_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

    B3.2/5.0

    Scored across 20 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to explore player profiles, ratings, game archives, leaderboards, clubs, and puzzles via the Chess.com API.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables querying Chess.com public data including player profiles, stats, games, and club information through natural language.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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