Skip to main content
Glama
Chess.com MCP Server

Chess.com MCP Server

by pab1it0

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.

Related MCP server: Chess MCP Server

Usage

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


Available Tools

10 tools
download_player_games_pgnC

Download PGN files for all games in a specific month from Chess.com

Inputs: username (required), year (required), month (required). Returns: result

get_club_membersC

Get members of a club on Chess.com

Inputs: url_id (required). Returns: result

get_club_profileC

Get information about a club on Chess.com

Inputs: url_id (required). Returns: result

get_player_current_gamesC

Get a player's ongoing games on Chess.com

Inputs: username (required). Returns: result

get_player_game_archivesC

Get a list of available monthly game archives for a player on Chess.com

Inputs: username (required). Returns: result

get_player_games_by_monthB

Get a player's games for a specific month from Chess.com

Inputs: username (required), year (required), month (required). Returns: result

get_player_profileC

Get a player's profile from Chess.com

Inputs: username (required). Returns: result

get_player_statsC

Get a player's stats from Chess.com

Inputs: username (required). Returns: result

get_titled_playersC

Get a list of titled players from Chess.com

Inputs: title (required). Returns: result

is_player_onlineA

Check if a player is currently online on Chess.com

Inputs: username (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action, such as downloading games, retrieving club info, or checking online status. There is no overlap or ambiguity between tool purposes.

    Naming Consistency5/5

    All tool names follow a clear verb_noun pattern using underscores (e.g., get_player_profile, download_player_games_pgn). The verbs (download, get, is) and nouns are consistently structured.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a Chess.com data retrieval server. It covers player data, clubs, and utilities without being too sparse or overwhelming.

    Completeness4/5

    The tool surface covers core read operations for players, clubs, and games. Minor gaps exist, such as missing tools for live ratings or tournament data, but the set is largely complete for typical queries.

    Maintenance

    ActivityNo data
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides Chess.com player data integration, enabling AI assistants to fetch real-time chess player profiles and comprehensive statistics including ratings, game counts, and performance metrics from Chess.com's public API.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to explore player profiles, ratings, game archives, leaderboards, clubs, and puzzles via the Chess.com API.
      2
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides access to Chess.com's public API, allowing AI assistants to fetch player information and statistics.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables querying Chess.com public data including player profiles, stats, games, and club information through natural language.
      9
      MIT