# Chessfolio

> Your whole chess life, in one place. Connect chess.com, Lichess and your OTB (ECF) games, and see your chess through stats no single platform can show. Free to use.

## Key pages

- Home: https://chessfolio.io/
- Markdown version of the homepage: https://chessfolio.io/index.md
- Sign up: https://chessfolio.io/signup
- Sign in: https://chessfolio.io/login

## What Chessfolio does

- Pulls chess.com, Lichess and over-the-board (ECF) games into one place, with PGN upload for everything else
- Full history backfill on day one, nightly sync top-ups after
- One dashboard: multi-platform rating chart, accuracy trend, win/draw/loss splits, online vs over-the-board comparison
- Engine game review with accuracies, move classifications and each game's critical moments
- Lichess puzzle tracking alongside the games
- A weekly report every Friday: one honest summary of the week, delivered by email as a shareable mini-report page
- Chessfolio Embed (https://embed.chessfolio.io) puts live fixtures, results and league tables on chess club websites

## Agent access

Chessfolio has a real agent surface. It is read-only except for nine narrow, owner-scoped write operations. None of them accepts a URL, a path or an uploaded file: what they take is PGN text, ids, labels and numbers sent in the call itself. Six kinds of tool:

- Personal chess data (needs a token): your own stats, games (list, single-game detail, attach_pgn and request_game_review), ratings, problem opening lines, weekly report and puzzles. get_weakness_profile is the cross-game diagnosis: every reviewed game's own moves bucketed by phase, clock pressure, piece, move kind, concept tag and conversion, ranked by a struggle score with a five-game floor, a delta against the previous window, and evidence game ids ready for get_critical_moments (whose matchesKnownWeakness now lists the profile ids each moment exhibits). Under /api/v1/me/weakness-profile. attach_pgn takes an exact game id from list_games plus one PGN string; it accepts no URL/path/file, validates one legal game, strips comments/variations and stores canonical PGN only. request_game_review takes the same kind of game id and queues (or, with an optional bounded wait up to 45s, waits for) Chessfolio's engine review of that game — an already-reviewed game returns its existing review for free. Neither tool can change results, ratings or metadata. Under /api/v1/me/* and MCP tools with auth "bearer".
- Personal study collection (needs a token): a second collection, separate from your played games, for games you want to STUDY — a classic, a friend's game. upload_study_game saves one PGN and dedupes on the MOVES: a re-upload whose headers, comments or clock tags differ from an existing entry lands on that same row rather than a duplicate, keeping its analysis and filling any not-yet-noted plies with the new comments. Separately, an upload whose full canonical text matches a game already analysed anywhere in Chessfolio's store, including a library game, comes back free. list_study_games lists the collection, request_study_analysis spends the same shared engine-review allowance as request_game_review, and delete_study_game removes one game and its notes from your own collection — irreversibly, but without touching the underlying analysed game record or anyone else's data. Under /api/v1/me/study* and the MCP tools with auth "bearer".
- Coaching state (needs a token): the memory a coaching agent works from. get_coaching_state reads the user's active training focuses (at most three at once, each with the weakness-bucket baseline snapshotted when it was set, where one was named, the same bucket read from the current window, and a measured improving / flat / worse trend, or unknown when either reading is missing), the last 20 coaching entries, the assignments still open, and how many positions are saved; get_weakness_profile ranks where the user's own moves go wrong across their reviewed games. Four writes, every one scoped to a coaching row the token holder owns and metered by one shared allowance of 60 an hour: set_training_focus (creates, retitles or resolves a focus, and never deletes one), add_coaching_entry (append-only, with every game and position reference proved owned before anything is stored; it never edits an entry's text, and makes two kinds of edit to an existing row: flipping a single owned, OPEN assignment to completed or skipped when it is given that assignment's id, and, when a result names a saved position, stamping that position's last-quizzed time and appending to its quiz history, which is how a quiz is recorded), save_position (copied from the user's own review when a game is named, up to 500 saved positions per user) and remove_saved_position (the only coaching row an agent can delete). list_saved_positions reads them back, including which are due for a quiz. The user can see and delete anything an agent wrote from their dashboard. Under /api/v1/me/coaching/* and the MCP tools with auth "bearer".
- Public tournament tools (no token): a Chess-Results tournament snapshot, a Round-1 pairing estimate and a next-round Swiss pairing estimate (the real FIDE Dutch engine over the live standings). Under /api/v1/tournaments/* and the MCP tools with auth "none". The estimates are not official pairings and snapshots may be stale.
- Public ECF rating calculator (no token): what a set of results does to an English Chess Federation rating, using the ECF's published K Rating algorithm, with the per-game working shown. At /api/v1/ecf/rating-change and the MCP tool calculate_ecf_rating_change. It is arithmetic, not an official ECF figure, and it does not cover new or partially-rated players.
- Public classic-games library (no token): around 50 curated historical and instructive games, each with editorial commentary, a source citation and full engine analysis behind it. list_library_games browses the list; get_library_game returns one full entry — deliberately no per-ply data, prose and provenance only. At /api/v1/library* and the MCP tools with auth "none".

- REST API: https://chessfolio.io/api/v1 (OpenAPI: https://chessfolio.io/openapi.json)
- MCP server: https://chessfolio.io/api/mcp (streamable HTTP; personal tools use `Authorization: Bearer <token>`, the public tools need no auth)
- Create a token: sign in → Settings → API access. Tokens are shown once and revocable. Only personal data needs one.
- Human docs: https://chessfolio.io/developers
- Authentication details: https://chessfolio.io/auth.md
- Discovery: https://chessfolio.io/.well-known/api-catalog · /.well-known/mcp.json · /.well-known/agent-skills/index.json