Classic Chess MCP

Connect an assistant to Classic Chess to find games, read PGNs, biographies and published annotations, save study plans with notes and shared progress, and play your puzzles. The hosted MCP URL is https://classicchess.com/mcp/.

Release availability

Version 0.1.1 connects to the hosted MCP endpoint and is available on PyPI. Use the browser setup guide below to connect an assistant, or install the optional Python stdio relay.

Browser users

Claude and ChatGPT browser users connect to the hosted URL and sign in with their own Classic Chess account. Follow the browser setup guide for the current menus, account-plan requirements and workspace permissions. Choose automatic OAuth client registration in Claude. ChatGPT's available read and write actions depend on its plan and workspace permissions.

Public searches work without account access. Approve library read and write access to save plans and read progress, and puzzle read and write access to play your puzzles and save the results. Revoke the connection in Classic Chess Settings. A Python installation is needed only for the optional stdio relay below.

Claude Code

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

Complete browser sign-in and approve library access. Enable Classic Chess in a new session and ask, for example: “Build a five-game rook-endgame study plan and save it to my account.”

Codex

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

Codex may start browser sign-in when adding the server. The login command also lets you connect again later. Plans, progress and puzzle results belong to the account you approve, and are shared with the Classic Chess website.

Optional Python stdio relay

This MIT-licensed package needs Python 3.10 or later and has no runtime dependencies. It relays newline-delimited MCP messages to the same server. Install it from PyPI into a virtual environment.

On Linux or macOS:

python3 -m venv classicchess-mcp-env
classicchess-mcp-env/bin/python -m pip install classicchess-mcp
classicchess-mcp-env/bin/classicchess-mcp --help

On Windows:

py -m venv classicchess-mcp-env
classicchess-mcp-env\Scripts\python -m pip install classicchess-mcp
classicchess-mcp-env\Scripts\classicchess-mcp --help

In a source checkout, install with python3 -m pip install . inside your virtual environment. The distribution name is classicchess-mcp. The website source ZIP is also available from the website.

Create a personal token in Settings with library:read and library:write, and with puzzles:read and puzzles:write for puzzles, then configure your MCP client's private environment:

{
  "mcpServers": {
    "classicchess": {
      "command": "FULL_PATH_TO_CLASSICCHESS_MCP",
      "env": {"CLASSICCHESS_API_TOKEN": "YOUR_PERSONAL_TOKEN"}
    }
  }
}

Replace FULL_PATH_TO_CLASSICCHESS_MCP with the absolute path to the executable in the virtual environment above (bin/classicchess-mcp on Linux/macOS, Scripts\classicchess-mcp.exe on Windows). Replace YOUR_PERSONAL_TOKEN only in your client's private configuration. Revoke the token in Settings. The relay writes only MCP messages to stdout and never prints credentials, follows redirects or sends credentials to another origin.

For local development, pass --base-url http://127.0.0.1:PORT, replacing PORT with your development server's port. The canonical HTTPS site and an explicitly selected HTTP loopback origin are accepted.

Tools and protocol

The study tools are search_players, search_games, get_game_pgn, get_annotations, get_player_bio, create_plan, update_plan, mark_studied and get_progress. Plan creation accepts 1–100 ordered game slugs and original notes. Reuse a stable idempotency key when retrying the same plan. update_plan performs one operation per call: metadata, reorder, a note, add a game or remove an item. Theme rules and evidence are at /api/v1/public/themes/.

The puzzle tools are get_puzzle_summary, next_puzzle, get_puzzle, get_puzzle_history and record_puzzle_result. Puzzles are for signed-in accounts. next_puzzle returns a random puzzle from the account's rotation with every accepted solver move; keep the solution hidden while the learner solves. Record each play once: missed at the first wrong move or when the solution is shown, solved for a clean finish. A first-try solve leaves the rotation until the learner resets puzzles on the website or in the app.

The server uses stateless Streamable HTTP with JSON responses. It supports protocol 2026-07-28 with per-request metadata and bound routing headers, plus the initialization flows for 2025-11-25, 2025-06-18 and 2025-03-26. It publishes OAuth discovery, supports dynamic client registration, requires S256 PKCE and accepts native loopback callbacks when the issuer is production HTTPS. Clients supporting fixed headers can use personal API tokens instead. Source-attributed annotations retain their source and reuse terms.