Developers
Read-only personal chess data, for agents
Chessfolio exposes your own chess record (games, stats, ratings, reports and puzzles) through a REST API and an MCP server, both authenticated with personal access tokens. Your personal data stays private: a token only ever reads its owner’s record, and there are no writes. Alongside it sits a small public surface, two token-less tools that read published Chess-Results tournament data.
Quick start
Create a token in Settings → API access
Sign in and open Settings → API access, give the token a name and copy it when it’s shown. It is shown exactly once; you can revoke it any time.
Call the REST API
Send the token as a bearer header. Every endpoint returns JSON about the token owner only.
curl -H "Authorization: Bearer cfp_…" https://chessfolio.io/api/v1/meOr connect over MCP
The MCP server speaks streamable HTTP at
https://chessfolio.io/api/mcp. In claude.ai, add it as a custom connector with that URL and the sameAuthorizationheader. In Claude Code:claude mcp add --transport http chessfolio https://chessfolio.io/api/mcp --header "Authorization: Bearer $TOKEN"
Your personal endpoints
Seven REST endpoints and seven matching MCP tools over one shared service layer, so a REST response and its MCP counterpart return the same data. Every one takes your token, reads only your own record, and answers a GET.
| REST endpoint | MCP tool | Returns |
|---|---|---|
| /api/v1/me | get_profile | The authenticated user's Chessfolio profile: display name, linked platform usernames, connected sources with sync freshness (last_synced_at), and total game count. |
| /api/v1/me/stats | get_chess_stats | Aggregate statistics over the user's games for a chosen window: win/draw/loss by colour, online vs over-the-board comparison, performance rating, records and streaks, recent form, weekday performance, opponent-strength breakdown, game-length breakdown, top openings, monthly form and average accuracy. |
| /api/v1/me/ratings | get_rating_progress | Rating series per provider and time control (including ECF over-the-board), each with start/end/delta over the window. |
| /api/v1/me/games | list_games | Paged list of the user's games (50 per page) across chess.com, Lichess, ECF (OTB), manual and PGN imports, with filters matching the chessfolio.io games library: provider, result, colour, time class, date range, move-count range, opening, opponent, opening-line prefix (lineMoves, as returned by get_problem_lines) and free-text search. accuracy is the effective accuracy (platform value preferred, chessfolio review value as fallback — accuracySource says which). |
| /api/v1/me/problem-lines | get_problem_lines | The 'lines that keep hurting': per-colour opening lines (6–24 plies) where the user's score drops at least 8 points below their colour baseline over at least 5 games, ranked by a struggle index of (drop × log2 of games). |
| /api/v1/me/report/latest | get_weekly_report | The user's most recent Friday weekly report as its frozen payload: per-source sections (chess.com / Lichess / OTB) with games, rating lines, best win and toughest defeat, plus puzzles — exactly what the email and the public share page render, with the share URL included. |
| /api/v1/me/puzzles | get_puzzle_stats | Cross-source puzzle activity and ratings: 12-week solve summary with win rate, volume bucketed to suit the window (day/week/month), and rating series for Lichess puzzles and chess.com tactics (chess.com is a peak-only rating — their API exposes no current value). |
Tournament tools
Two extra tools read published tournament data straight from chess-results.com. They need no token and touch none of your account: point them at a tournament number and they answer for anyone. Both are GET, like the personal endpoints.
| REST endpoint | MCP tool | Returns |
|---|---|---|
| /api/v1/tournaments/{tnr}/state | get_tournament_state | Public, read-only snapshot of any Chess-Results tournament — no token needed (source: chess-results.com). |
| /api/v1/tournaments/{tnr}/round1 | estimate_round1 | Public, read-only ESTIMATE of Round-1 pairings for a Chess-Results tournament — no token needed (source: chess-results.com). |
Parameters
- tnr
- Required. The Chess-Results tournament number, for example
651260. In a REST path it is digits only; the MCP tools also accept a full chess-results.com tournament URL. - target
- Optional, on
round1only. A player name (case-insensitive) to return just their estimated board.
No token, no header. Point curl at a tournament number:
curl https://chessfolio.io/api/v1/tournaments/651260/state
curl "https://chessfolio.io/api/v1/tournaments/651260/round1?target=Wesson"An estimate, not a pairing. estimate_round1 derives boards from the seed list, so isEstimate is always true. The arbiter's official draw can differ.
Colour is a coin-flip. Round-1 colours turn on the initial-colour draw, so trust the estimated opponent far more than the estimated colour.
Snapshots can be stale. State carries a snapshotAt timestamp and is a short-lived scrape, not a live feed. Read the timestamp before you rely on it.
Read from chess-results.com. Both tools scrape published Chess-Results data. If that page layout changes they fail loudly rather than return half-parsed rows.
The fine print, up front
Read-only. There are no write endpoints on either surface, and none are planned for this phase.
Owner-scoped tokens. A personal token only ever reads its creator's data, with no cross-user access. The public tournament tools sit outside this entirely: they read published Chess-Results data and touch no account.
Rate-limited. 120 requests per minute per user on the personal surface, shared across REST and MCP. The public tournament endpoints are limited separately, to 60 requests a minute per IP.
Downsampled rating series. Series longer than 60 points are evenly downsampled (first and last points always kept); responses say when this happened.
OTB games have no move lists. Over-the-board (ECF) games carry results and ratings but no moves, so they are excluded from problem-lines analysis.
Tokens are shown once. Only a fingerprint is stored. Tokens are revocable any time in Settings and revocation takes effect on the next request.
Machine-readable discovery
Everything above is also published where agents look for it.
- /openapi.jsonOpenAPI 3.1 description of the REST surface
- /.well-known/api-catalogRFC 9727 API catalog linkset
- /.well-known/mcp.jsonMCP server card with full tool schemas
- /.well-known/agent-skills/index.jsonAgent-skills index, one skill per MCP tool
- /llms.txtPlain-language site summary for agents
- /auth.mdAuthentication details as markdown
Point an agent at your chess
Create a token in Settings and you’re one curl away. No Chessfolio account yet? It’s free.