Classic Chess · MCP

MCP server

Classic Chess runs a Model Context Protocol server at https://classicchess.com/mcp/. Its tools find players and games, read PGNs, annotations and biographies, create and update study plans, mark games studied, read progress, and play the account’s puzzles. Public reads need no account. Saving plans and reading progress use OAuth with the library:read and library:write scopes; the website library shares the same plans and progress. Puzzles are for signed-in accounts and use puzzles:read and puzzles:write; the website and the Android app share the same results.

This page covers terminal clients, the stdio relay and direct agent use.

Claude Code and Codex

With Claude Code installed, run:

claude mcp add --scope user --transport http classicchess https://classicchess.com/mcp/
claude mcp login classicchess

With Codex installed, run:

codex mcp add classicchess --url https://classicchess.com/mcp/
codex mcp login classicchess --scopes library:read,library:write,puzzles:read,puzzles:write

Complete browser sign-in and approve the permissions the client should have. Codex may start sign-in when adding the server. Start a new assistant session to use the connection.

Optional Python relay

For clients that require a local stdio process, install the MIT-licensed classicchess-mcp package from PyPI. It requires Python 3.10 or later. In a Python virtual environment, run:

python -m pip install classicchess-mcp
classicchess-mcp --help

Create a personal API token in Settings with library:read and library:write, and with puzzles:read and puzzles:write for puzzles. Configure classicchess-mcp as the client’s command and keep CLASSICCHESS_API_TOKEN in its private environment. The standalone source ZIP and installation README are also available.

Agent study-plan recipe

Nine of the tools find players and games, read PGNs, annotations and biographies, create or update plans, mark games studied or unstudied, and read progress. A saved plan contains 1–100 ordered games with your study notes. For agents using the API directly, start with llms.txt and follow this recipe:

  1. Read /api/v1/public/themes/ for theme slugs, written rules, measured precision and curation evidence.
  2. Use search_games with a theme and any player, event, ECO or result filters, then use each result's slug in plan items. Read PGNs and source-attributed annotations, and write your own study notes. Book-only games and their notes are searchable at /api/v1/annotated/books/BOOK_SLUG/games/?q=TEXT&author=AUTHOR.
  3. Call create_plan with a name, stable idempotency key and 1–100 ordered {game, note} items. An identical retry returns the existing plan.
  4. Call mark_studied as you finish games, then get_progress to adapt the plan. The viewer and library share this state. The beginner guide saves no place.

Puzzles

Five tools work with the signed-in account’s puzzles from master games. Each account has its own rotation: a puzzle solved on the first try leaves it until the learner resets puzzles on the website or in the app, and a missed one stays.

  1. Call next_puzzle for a random puzzle from the rotation, passing after with the puzzle just played. It returns the game so far, the position and every accepted solver move. Keep the solution hidden while the learner solves.
  2. Call record_puzzle_result once per play: missed at the first wrong move or when the solution is shown, solved for a clean finish. This needs puzzles:write.
  3. Use get_puzzle_summary, get_puzzle_history and get_puzzle to read the figures, the played puzzles and one puzzle again.

Rate limits

Valid personal tokens get bounded budgets counted per token, so agents behind the same connection have separate allowances. Anonymous limits stay the same. HTTP 429 means slow down; honor Retry-After. These limits manage server load and do not involve billing. The game result stays visible in both learner styles.