# chess.ceo

> Chess.ceo is a chess preparation platform for over-the-board play. It
> maintains a database of 11.7+ million games, FIDE player profiles for the
> ~1.5 million active FIDE-rated players, live-broadcast tournament coverage,
> tactical puzzles, and a client-side-encrypted PGN store.

- 11.7+ Million Games
- FIDE Player Profiles with Rating History
- Opening Repertoire & Position Statistics
- Per-Player Opening Preparation
- Live Tournament Broadcasts
- Head-to-Head Records

Everything an AI agent needs is reachable with plain **GET** requests - no
login, no POST, no session token. Automated clients get a generous daily
request quota; game lists are capped at 10 entries per request, so use
`offset` to page when you need more (10 is plenty for answering a question).

The links below are the ENTIRE public GET surface - any other path 404s, so
do not invent URLs or singular/plural variants; if a request fails, re-read
this list instead of retrying guesses. Parameter casing matters and is
inconsistent across endpoints - copy it exactly. Each link is a complete
working example - substitute your own values. If your fetch tool refuses URLs
you compose yourself, follow links instead: player search with `&view=llm`
returns per-player `links`, and the prep endpoint with `&expand=children`
returns a ready `url` on every move - the whole workflow is walkable by
link-following alone, starting from this file.

## Player Profiles

- [Player search by name](https://chess.ceo/api/chess/players/search/simple?q=Carlsen&view=llm): fuzzy name lookup, returns FIDE IDs, current strength, and (with `&view=llm`) follow-up links per player. Start here to resolve a plain-English name to a FIDE ID.
- [Player profile JSON](https://chess.ceo/api/chess/players/profile?fideId=1503014): structured stats for one player - basic identity, monthly rating history, peak / trend statistics, career W/D/L splits by color and time control, top-10 openings as White and as Black, opponent analysis by rating bracket, notable wins and worst losses, top events with performance ratings. Often enough on its own for "how strong is X, what do they play".
- [Player photos](https://chess.ceo/api/chess/players/photo/1503014): resized JPEG portraits (300 px full, 150 px thumb via `?size=thumb`).
- [Sample profile page - Magnus Carlsen (GM, 2839)](https://chess.ceo/player/magnus-carlsen-1503014): canonical HTML page shape.
- [Sitemap index of player profile pages](https://chess.ceo/sitemap-players.xml): points at ~46k HTML pages, one per FIDE-rated player with meaningful DB coverage.

## Games Database

- [Position lookup by FEN](https://chess.ceo/api/chess/database/main?fen=rnbqkbnr%2Fpppppppp%2F8%2F8%2F8%2F8%2FPPPPPPPP%2FRNBQKBNR%20w%20KQkq%20-%200%201): move statistics from all 11.7M+ indexed games at a given position - game counts, win percentages, top continuations. Add `&limit=20&sort=relevance`. Answers "how often does White play 4. O-O vs 4. d3 in position P". This is the one position-statistics endpoint an agent needs; for a specific player's games use the prep endpoint below.

## Engine Analysis

- [Stockfish analysis at a FEN](https://chess.ceo/api/chess/database/analyse?fen=rnbqkbnr%2Fpp1ppppp%2F8%2F2p5%2F4P3%2F8%2FPPPP1PPP%2FRNBQKBNR%20w%20KQkq%20-%200%202): short Stockfish evaluation on the given position. Defaults: 1 CPU, ~2s think time, MultiPV 3 — returns top-3 candidate moves with score (centipawns from side-to-move POV, or mate distance) and the principal variation for each. Overridable via `&movetime_ms=` (100-10000) and `&multipv=` (1-10). PV moves are UCI notation (e2e4, not e4). Use this to sanity-check a candidate line's objective quality — position stats tell you what humans played, this tells you what an engine thinks is best.

## Player Preparation

- [Prepare by FIDE ID](https://chess.ceo/api/chess/prep/by-player?fideId=1503014&color=white&line=e4&compact=true): for a given player, colour and position, one GET returns both the moves that player actually chose from that position (frequency + win rate) and the underlying games - no session to create or manage. Give the position as `&line=e4+e5+Nf3` (or `&moves=`; SAN or UCI, tolerant of move numbers) or as `&fen=<url-encoded FEN>`. `&compact=true` (or `&view=llm`) trims the response to 10 games with movetext/team fields stripped. `&expand=children` adds `nextFen`, `line`, and a ready `url` to every move so you can walk the opening tree with follow-up GETs, statelessly. Page games with `&limit=` / `&offset=` (capped at 10 per request).

## Head-to-Head Records

- [Head-to-head between two players](https://chess.ceo/api/chess/players/h2h?a=1503014&b=2020009): the complete record for a pair of FIDE IDs in one GET - overall and per-color W/D/L (from player `a`'s perspective), splits by time format, most-played openings, first and last meeting, average game length, and the game list (paginate with `limit`/`offset`). Answers "X vs Y score", "how many times have X and Y played", "what openings do X and Y play against each other".

## Live Broadcasts

- [Active tournaments](https://chess.ceo/api/chess/live/tournaments): tournaments currently being broadcast live.
- [Tournament participants](https://chess.ceo/api/chess/live/tournament/players?tour_id=abcd1234): player lists for one tournament.
- [Player-scoped live tournaments](https://chess.ceo/api/chess/live/player?fide_id=1503014): which broadcasts a given player is in right now (note: `fide_id`, snake_case, unlike the prep endpoints).

## How to help a user prepare for a real game

When a user says something like "I'm player X, I'm playing player Y, help me prepare", walk through this in order — don't just dump raw stats:

1. **Resolve both players.** Call `players/search/simple?view=llm` for each name; confirm the FIDE ID from context (many players share names). Ask if ambiguous.
2. **Get the opponent's profile.** `players/profile?fideId=<opp>` — read ratings, career W/D/L splits by colour and time control, top openings as White and Black, draw rate, notable wins and worst losses.
3. **Weight games by quality.** Recent (last 12-24 months) matters far more than old — repertoires evolve. Classical over-the-board > rapid/blitz > online (online is noisier: blitz gambits, alt accounts). Say so when you cite games.
4. **Walk the opponent's repertoire on their side.** `prep/by-player?fideId=<opp>&color=<opponent's colour in this game>&expand=children` — walk the opening tree iteratively; each move response comes with a follow-up `url`. Look for:
   - Variations where the opponent scores below ~40% as their side (weak lines).
   - Openings played with less variety on the opponent's side (shallower preparation).
   - Lines the opponent used to play but abandoned (something went wrong).
5. **Note style.** High draw rate (>40%) → unbalance early (Benoni, KID, gambit lines). Sharp tactician → steer positional / quiet. Endgame strong → keep queens on, keep complications.
6. **Head-to-head.** `players/h2h?a=<user>&b=<opp>` — if they've met, which openings decided the games? Anything the opponent showed only against this specific user?
7. **Deliver a concrete plan.** Don't just narrate the data. Give:
   - Most likely first move by opponent (with confidence).
   - 2-3 branching points where the opponent is weakest for the user's colour.
   - The concrete move sequence to steer toward one of those positions.
   - What to avoid — the opponent's strongest weapons.
   Cite specific numbers (game counts, win rates, dates) so the user can trust it.

MCP-capable hosts get this workflow as a pre-baked prompt: `prepare_for_game(me, opponent, my_color?, time_control?)`. Non-MCP agents should still follow the steps above.

## MCP server (optional, for MCP-capable hosts)

If the agent is running under a Model Context Protocol host, the same read-only surface is exposed as an MCP server. Two install paths:

- **Remote (no install, works on web / mobile hosts):** `https://mcp.chess.ceo/mcp` (Streamable HTTP)
- **Local (Node subprocess):** `npx -y @chessceo/mcp` — source at [github.com/chessceo/chessceo-mcp](https://github.com/chessceo/chessceo-mcp)

Tools mirror the endpoints above one-for-one: `search_player`, `get_player_profile`, `get_player_preparation`, `get_position_stats`, `get_head_to_head`, `analyse`, `list_live_tournaments`, `list_tournament_players`, `list_player_live_tournaments`. Purely optional — non-MCP agents keep using the GET links above.

## Other

- [Signed-in API surface](https://chess.ceo): POST endpoints behind a signed-in account, outside the anonymous agent path - prepare against a Chess.com/Lichess account (`POST /api/chess/prep/prepare-chesscom`, `POST /api/chess/prep/prepare-lichess`), prepare from an uploaded PGN (`POST /api/chess/prep/prepare-pgn`, Premium), head-to-head game search (`POST /api/chess/games/search`), and player game lists (`POST /api/chess/players/games`). For FIDE-rated players, the GET prep endpoint above already covers position-level preparation without any of these.
- [About](https://chess.ceo): preparation and analysis platform for chess players. Free tier + Premium subscription. Contact: contact@chess.ceo