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, three 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/me
```
Or 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 same Authorization header. In Claude Code:
```
claude mcp add --transport http chessfolio https://chessfolio.io/api/mcp --header "Authorization: Bearer $TOKEN"
```

Connecting a client

Any MCP client (Claude Code, claude.ai connectors, Codex, Hermes and the rest) needs three things: the server URL, your token as a bearer header, and the tool list. Point it at https://chessfolio.io/api/mcp over streamable HTTP, send Authorization: Bearer cfp_…, and it reads every tool schema from the discovery documents. The public tournament tools need no header.

/.well-known/mcp.json /openapi.json

Your personal endpoints

Token required

Eight REST endpoints and eight 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.

The eight personal REST endpoints and their matching MCP tools, every one requiring a token
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/games/{id}	get_game	One of the user's games in full: the same summary fields as list_games plus its moves and, where a Chessfolio review exists, a review summary. `movesSource` says what the moves are — `pgn` when the full game is stored (reviewed or PGN-attached games), `opening-only` when only the recorded opening line is known, or null for an OTB/online game with no attached PGN, which carries no moves at all (the endpoint never fabricates moves). `review` is present only when a Chessfolio analysis exists: accuracy for both colours and for the user, the key critical moments and a move-classification histogram (no per-ply detail).
/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

Public · no token

Three 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. All are GET, like the personal endpoints.

The two public tournament REST endpoints and their matching MCP tools, neither requiring a token
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).
/api/v1/tournaments/{tnr}/pairings	estimate_pairings	Public, read-only ESTIMATE of the next round's pairings for a Chess-Results Swiss 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 round1 and pairings. A player name (case-insensitive) to return just their estimated board (with a what-if scenario table on pairings).

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.

Point an agent at your chess

Create a token in Settings and you’re one curl away. No Chessfolio account yet? It’s free.

Create a token Start your Chessfolio

Quick start

1.Create a token in Settings → API access

2.Call the REST API

3.Or connect over MCP