Chess.com MCP Server

Instructions

Implementation Reference

• src/chess_mcp/server.py:239-268 (handler)

  The core handler function decorated with @mcp.tool that implements the download_player_games_pgn tool. It constructs the Chess.com PGN API endpoint and fetches the PGN data using the shared make_api_request helper.
  @mcp.tool(description="Download PGN files for all games in a specific month from Chess.com") async def download_player_games_pgn( username: str, year: int, month: int ) -> str: """ Download PGN files for all games in a specific month from Chess.com. Args: username: The Chess.com username year: Year (YYYY format) month: Month (MM format, 01-12) Returns: Multi-game PGN format text containing all games for the month """ month_str = str(month).zfill(2) logger.info( "Downloading player games PGN", username=username, year=year, month=month_str ) result = await make_api_request( f"player/{username}/games/{year}/{month_str}/pgn", accept_json=False ) return result
• src/chess_mcp/server.py:239-268 (registration)

  The @mcp.tool decorator registers this function as an MCP tool with the FastMCP server instance.
  @mcp.tool(description="Download PGN files for all games in a specific month from Chess.com") async def download_player_games_pgn( username: str, year: int, month: int ) -> str: """ Download PGN files for all games in a specific month from Chess.com. Args: username: The Chess.com username year: Year (YYYY format) month: Month (MM format, 01-12) Returns: Multi-game PGN format text containing all games for the month """ month_str = str(month).zfill(2) logger.info( "Downloading player games PGN", username=username, year=year, month=month_str ) result = await make_api_request( f"player/{username}/games/{year}/{month_str}/pgn", accept_json=False ) return result
• src/chess_mcp/server.py:26-81 (helper)

  Shared helper function used by download_player_games_pgn to make the actual API request to Chess.com with PGN content type.
  async def make_api_request( endpoint: str, params: Optional[Dict[str, Any]] = None, accept_json: bool = True ) -> Union[Dict[str, Any], str]: """ Make a request to the Chess.com API. Args: endpoint: The API endpoint to request params: Optional query parameters accept_json: Whether to accept JSON response (True) or PGN (False) Returns: JSON response as dict or text response as string Raises: httpx.HTTPError: If the request fails """ url = f"{config.base_url}/{endpoint}" headers = { "accept": "application/json" if accept_json else "application/x-chess-pgn" } logger.debug( "Making API request", endpoint=endpoint, url=url, accept_json=accept_json, has_params=params is not None ) async with httpx.AsyncClient() as client: try: response = await client.get(url, headers=headers, params=params or {}) response.raise_for_status() if accept_json: result = response.json() logger.debug("API request successful", endpoint=endpoint, response_type="json") return result else: result = response.text logger.debug("API request successful", endpoint=endpoint, response_type="text") return result except httpx.HTTPError as e: logger.error( "API request failed", endpoint=endpoint, url=url, error=str(e), error_type=type(e).__name__ ) raise