Chess.com

What is chess-mcp?

chess-mcp is a Model Context Protocol (MCP) server designed to provide AI assistants with access to public data from Chess.com. It acts as an intermediary, translating Chess.com's Published Data API into standardized MCP interfaces, enabling AI to easily search and analyze chess-related information.

How to use chess-mcp?

chess-mcp can be run in two primary ways:

Docker (Recommended)

1. Ensure Docker is installed on your system.

2. Edit your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on Mac, %APPDATA%/Claude/claude_desktop_config.json on Windows, or ~/.config/Claude/claude_desktop_config.json on Linux).

3. Add the following JSON configuration to mcpServers:

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

Running with UV

1. Install uv by running: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Unix/macOS
   .venv\Scripts\activate     # On Windows
   uv pip install -e .
   

3. Edit your Claude Desktop configuration file (locations listed above).

4. Add the following JSON configuration to mcpServers:

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

Key Features of chess-mcp

• Access to Chess.com Data: Provides access to player profiles, stats, game records, club information, and titled player lists.
• Search Capabilities: Allows searching games by date and player.
• Player Status Check: Enables checking a player's online status.
• No Authentication Required: Utilizes Chess.com's public API, eliminating the need for authentication.
• Docker Support: Offers easy deployment and management through Docker containerization.
• Interactive Tools for AI: Provides configurable tools for AI assistants to interact with Chess.com data.

Use Cases of chess-mcp

• AI Chess Analysis: AI assistants can leverage this server to analyze chess games, player performance, and trends.
• Chess Data Research: Researchers can programmatically access and process Chess.com data for various studies.
• Custom Chess Applications: Developers can build custom applications that integrate with Chess.com data through a standardized protocol.
• Educational Tools: Create educational tools that provide insights into chess strategies and player statistics.

FAQ about chess-mcp

• What is MCP? MCP stands for Model Context Protocol, a protocol designed to allow AI assistants to interact with external data sources in a standardized way.
• Does chess-mcp require a Chess.com account? No, it uses Chess.com's public API, so no authentication or Chess.com account is required.
• Can I contribute to chess-mcp? Yes, contributions are welcome. You can open an issue or submit a pull request on the project's GitHub repository.
• How do I run tests for chess-mcp? After installing development dependencies (uv pip install -e ".[dev]"), you can run tests using pytest or pytest --cov=src --cov-report=term-missing for a coverage report.

Chess.com MCP Server

A Model Context Protocol (MCP) server for Chess.com's Published Data API.

This provides access to Chess.com player data, game records, and other public information through standardized MCP interfaces, allowing AI assistants to search and analyze chess information.

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

Features

• Access player profiles, stats, and game records
• Search games by date and player
• Check player online status
• Get information about clubs and titled players
• No authentication required (uses Chess.com's public API)
• Docker containerization support
• Provide interactive tools for AI assistants

The list of tools is configurable, so you can choose which tools you want to make available to the MCP client.

Usage

Docker (Recommended)

The easiest way to run chess-mcp with Claude Desktop is using Docker. If you don't have Docker installed, you can get it from Docker's official website.

Edit your Claude Desktop config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Then add the following configuration:

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

Running with UV

Alternatively, you can run the server directly using UV. Edit your Claude Desktop config file (locations listed above) and add the server configuration:

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

Note: if you see Error: spawn uv ENOENT in Claude Desktop, you may need to specify the full path to uv or set the environment variable NO_UV=1 in the configuration.

Development

Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.

This project uses uv to manage dependencies. Install uv following the instructions for your platform:

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

You can then create a virtual environment and install the dependencies with:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Testing

The project includes a test suite that ensures functionality and helps prevent regressions.

Run the tests with pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Available Tools

Player Information

• get_player_profile - Get a player's profile from Chess.com
• get_player_stats - Get a player's stats from Chess.com
• is_player_online - Check if a player is currently online on Chess.com
• get_titled_players - Get a list of titled players from Chess.com

Games

• get_player_current_games - Get a player's ongoing games on Chess.com
• get_player_games_by_month - Get a player's games for a specific month from Chess.com
• get_player_game_archives - Get a list of available monthly game archives for a player on Chess.com
• download_player_games_pgn - Download PGN files for all games in a specific month from Chess.com

Clubs

• get_club_profile - Get information about a club on Chess.com
• get_club_members - Get members of a club on Chess.com

License

MIT

---