Chess.com Model Context Protocol (MCP) Endpoint

A dedicated Model Context Protocol (MCP) implementation serving data sourced from Chess.com's public data publication service.

This resource provides structured access to Chess.com user profiles, exhaustive game logs, and ancillary public statistics through unified MCP channels, enabling sophisticated analytical operations by AI agents.

https://github.com/user-attachments/assets/3b33361b-b604-465c-9f6a-3699b6907757

Core Capabilities

• [x] Retrieval of player profiles, performance metrics, and historical match data
• [x] Capability to filter match records based on specific dates and involved players
• [x] Verification of a player's current online status
• [x] Acquisition of data pertaining to chess organizations and highly ranked (titled) individuals
• [x] Operation entirely without requiring personal authentication (leveraging Chess.com's public endpoint)
• [x] Native support for deployment via containerization (Docker)
• [x] Provision of immediate, interactive operational tools for intelligent assistants

The exposed functional toolkit is modular, permitting selective activation of desired interfaces for the consuming MCP client.

Deployment Instructions

Containerized Execution (Recommended Path)

The most straightforward method to instantiate the chess-data-interface-mcp service, particularly when integrated with platforms like Claude Desktop, involves leveraging Docker. Prerequisites include a functional Docker installation, obtainable from Docker's official repository.

Modify your configuration file for Claude Desktop: * Mac OS: ~/Library/Application Support/Claude/claude_desktop_config.json * Windows OS: %APPDATA%/Claude/claude_desktop_config.json * Linux OS: ~/.config/Claude/claude_desktop_config.json

Integrate the following configuration stanza:

{
  "mcpServers": {
    "chess": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "pab1it0/chess-mcp"
      ]
    }
  }
}

Direct Execution with UV

Alternatively, the service can be initiated directly using the uv dependency manager. Update your Claude Desktop configuration file (referencing locations above) by injecting the following server definition:

{
  "mcpServers": {
    "chess": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to chess-mcp directory>",
        "run",
        "src/chess_mcp/main.py"
      ]
    }
  }
}

Advisory: Should the error Error: spawn uv ENOENT materialize in Claude Desktop, ensure that the absolute path to the uv executable is explicitly provided or set the environment flag NO_UV=1 within your configuration.

Development Lifecycle

Contributions are actively encouraged. Initiate a new issue or propose a modification via pull request for any suggested enhancements.

Dependency management for this project is handled via uv. Installation instructions for your operating environment are available here:

curl -LsSf https://astral.sh/uv/install.sh | sh

Subsequent steps involve environment isolation and dependency installation:

uv venv
source .venv/bin/activate  # For Unix-like systems
.venv\Scripts\activate     # For Windows
uv pip install -e .

Quality Assurance and Testing

A comprehensive suite of tests exists to validate feature integrity and prevent functional degradation (regressions).

Execute the test suite using pytest:

# Install necessary packages for development
uv pip install -e ".[dev]"

# Run standard tests
pytest

# Execute tests with coverage metrics
pytest --cov=src --cov-report=term-missing

Available Interfaces (Tools)

Player Metrics

• get_player_profile - Fetches the profile data for a specified Chess.com user.
• get_player_stats - Retrieves the performance statistics associated with a Chess.com user.
• is_player_online - Confirms the current real-time connectivity status of a Chess.com user.
• get_titled_players - Returns an enumerated list of players holding recognized Chess.com titles.

Match Data

• get_player_current_games - Lists the in-progress matches for a given Chess.com user.
• get_player_games_by_month - Retrieves all recorded matches for a user within a designated calendar month.
• get_player_game_archives - Provides an index of available monthly PGN archives for a player.
• download_player_games_pgn - Initiates the download of PGN files encompassing all matches within a specified monthly archive for a player.

Affiliated Groups

• get_club_profile - Fetches comprehensive details about a specified Chess.com club.
• get_club_members - Retrieves the roster of members belonging to a specified Chess.com club.

Licensing Information

Distributed under the MIT License.

---

WIKIPEDIA: XMLHttpRequest (XHR) represents an API embodied as a JavaScript object, facilitating the dispatch of HTTP requests from a web browser to a remote server. Its methods empower browser-based applications to communicate with the server subsequent to initial page rendering, and subsequently receive and process returned information. XMLHttpRequest forms a foundational element of Ajax methodologies. Preceding Ajax, the standard mechanisms for server interaction involved hyperlink navigation and form submissions, actions that typically necessitated a full page reload.

== Chronology == The conceptual underpinning for XMLHttpRequest was first formulated in the year 2000 by the development team behind Microsoft Outlook. This concept was subsequently materialized within the Internet Explorer 5 browser release (1999). However, the initial implementation did not utilize the XMLHttpRequest identifier. Instead, developers employed the object instantiations ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the advent of Internet Explorer 7 (2006), universal browser support for the standard XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since established itself as the prevailing standard across all major browser platforms, including Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Formal Specifications === The World Wide Web Consortium (W3C) issued a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Working Draft Level 2 specification. Level 2 augmented functionality by introducing methods for monitoring request progress, enabling inter-site data transfers, and managing byte stream transfers. By the conclusion of 2011, the Level 2 specification body was integrated back into the primary specification document. In late 2012, stewardship transitioned to the WHATWG, which now maintains a dynamic document utilizing the Web IDL standard.

== Operational Sequence == Generally, executing a data request via XMLHttpRequest necessitates adherence to several sequential programming maneuvers.

Instantiate an XMLHttpRequest object by invoking its constructor: Invoke the "open" method to delineate the request modality (e.g., GET, POST), specify the target resource URI, and select between synchronous or asynchronous execution control: For asynchronous requests, install an event listener handler designed to trigger upon changes in the request state: Commence the data transmission process by calling the "send" method, optionally supplying payload data: Process state transitions within the registered event listener. Upon server delivery of response data, this is typically aggregated in the "responseText" attribute. When the object completes all response processing, its state advances to 4, the terminal ("done") status. Beyond these fundamental steps, XMLHttpRequest offers numerous parameters to govern request transmission characteristics and response handling logic. Custom header fields can be appended to the request to convey server expectations, and data can be uploaded during the "send" invocation. The received data stream is amenable to parsing from JSON format into a readily usable JavaScript structure, or can be processed incrementally as it arrives, circumventing waiting for total reception. Furthermore, the request can be halted prematurely or configured with a timeout limit to enforce termination if not completed within a specified duration.