Classic Chess MCP

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

Release availability

Version 0.1.0 is a development preview of the relay. The Python package is available on PyPI; the hosted MCP endpoint and browser setup guide are awaiting the website deployment. Until then, use a local Classic Chess development server with --base-url http://127.0.0.1:PORT, replacing PORT with its port.

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. 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

Codex may start browser sign-in when adding the server. The login command also lets you connect again later. Plans and progress 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 will also be available after the website deployment.

Create a personal token in Settings with library:read and library:write, 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 nine 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 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.