Chess.com MCP Server

Chess.com (Published Data)

Chess.com exposes public player, game, club, and tournament data through its Published Data API. Data is read-only and reflects what is visible on the site without logging in as that user. Private data (game chat, conditional moves, account settings) is not available.

Workflows

• Player lookup: Fetch profile first (username is case-insensitive). Use last_online on the profile when the user asks if someone is active recently; there is no working separate is-online PubAPI route anymore. Pull stats when they want ratings or win/loss records by time control.
• Game history: List game archives to see which months exist, then fetch a month as JSON for structured fields (opponent, result, PGN embedded per game) or as a single PGN file for analysis tools.
• Full moves: Chess.com embeds complete movetext in each game's pgn field. For one finished game by URL, use the single-game lookup tool — it returns parsed moves_san. Per-move Brilliant/Blunder/Excellent labels from Game Review are not in PubAPI — only game-level accuracies percentages when present. Do not invent move classifications.
• Do not guess month: Pass latest_month=true on game tools when you want the newest archive instead of inventing year/month.
• In-progress daily chess: Use current-games for active daily games; use the to-move variant when the user only cares about clocks waiting on them.
• Clubs and titles: Resolve a member's clubs from the player endpoint family, then fetch club profile or member list by club URL slug (the path segment from chess.com/club/…).
• Daily puzzle: Fetch the daily puzzle when the user wants today's puzzle FEN or metadata — not a substitute for in-app puzzle rush stats (those live under player stats when present).

Data model

• Usernames are public handles (e.g. hikaru) or a chess.com/member/{username} URL.
• Game archives are monthly (YYYY / MM). There is no single "all games" endpoint — walk archives or pull one month at a time.
• Time classes include bullet, blitz, rapid, and daily in stats and game records.
• JSON-LD: Responses include @id and related metadata; agents can ignore JSON-LD keys when extracting user-facing facts.

Gotchas

• Freshness: Public game and stats data can lag live play by roughly half a day to a day; very recent games may not appear in the monthly archive yet.
• Rate limits: Chess.com limits parallel requests. Responses include a cache object (source, age_seconds). Prefer cached reads in one agent run; on HTTP 429 the client retries with backoff.
• 404: Unknown username, club slug, or month with no archive returns not found — confirm spelling and that the profile is public.
• Large months: Active players can have hundreds of games in one month; use max_games when the user only needs a sample or the latest games.
• No moves on behalf of users: This integration cannot send moves or change account settings.