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.

Connection default

The user saves their Chess.com member name on the MCPBundles connection (public handle, not a password). On player-scoped tools:

• Omit username to query that saved member (ratings, archives, clubs, and games for "me").
• Pass username to query any other public player (students, opponents, stream guests).

Club, puzzle, and titled-player tools do not take a player username unless the workflow needs a specific member.

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.