Chess.com MCP Server

Chess.com MCP Server

What is Chess.com MCP Server about?

Chess.com MCP Server exposes Chess.com’s public data (player profiles, statistics, game archives, club information, and online status) via Model Context Protocol endpoints. AI assistants can query these endpoints to retrieve structured chess data without dealing directly with the raw Chess.com API.

How to use Chess.com MCP Server?

1. Docker (recommended) – Add the following entry to Claude Desktop’s claude_desktop_config.json:

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

2. Direct execution with UV – Install uv, then run the server:

uv venv
source .venv/bin/activate   # or .venv\\Scripts\\activate on Windows
uv pip install -e .
uv run src/chess_mcp/main.py

Update Claude Desktop’s config to use the uv command as shown in the README.

Key features of Chess.com MCP Server

• Retrieve player profiles, stats, and online status
• Search a player’s current games and historic games by month
• Download monthly game archives in PGN format
• Access club profiles and member lists
• List titled players on Chess.com
• No authentication required (uses public API)
• Docker container available for easy deployment
• UV‑based Python environment for local development
• Configurable toolset so assistants expose only needed functions

Use cases of Chess.com MCP Server

• AI‑driven chess coaching – An assistant can fetch a learner’s recent games, analyze patterns, and suggest improvements.
• Live game monitoring – Bots can check whether a user is online and retrieve ongoing games for real‑time commentary.
• Statistical dashboards – Aggregate player statistics across many users for leaderboards or community insights.
• Club management tools – Pull club member rosters and activity for automated newsletters or event planning.
• Research & content creation – Pull PGN archives to generate annotated game collections or highlight memorable matches.

FAQ from the Chess.com MCP Server

• Do I need an API key? No. The server uses Chess.com’s public endpoints which do not require authentication.
• Can I run the server without Docker? Yes, using UV as described above, or by installing the requirements manually (pip install -e .).
• How do I limit which tools are exposed? The server’s configuration allows you to enable or disable individual tool functions before starting the MCP service.
• What Python version is required? Python 3.9 or newer is recommended.
• Is there test coverage? Yes, the repository includes a pytest suite with optional coverage reporting.

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

---