Chess.com MCP Server

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

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 the Claude Desktop config file and add the server configuration:

{
  "mcpServers": {
    "chess": {
      "command": "uv",
      "args": [ "--directory", "", "run", "src/chess_mcp/main.py" ]
    }
  }
}

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:

uv pip install -e ".[dev]"\n\n# Run the tests
pytest\n\n# Run with coverage report
pytest --cov=src --cov-report=term-missing

Available Tools# Player Information

• get_player_profile
• get_player_stats
• is_player_online
• get_titled_players

Games

• get_player_current_games
• get_player_games_by_month
• get_player_game_archives
• download_player_games_pgn

Clubs

• get_club_profile
• get_club_members