home / mcp / chess.com mcp server

Chess.com MCP Server

A Model Context Protocol 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.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can access Chess.com data through a dedicated MCP server that exposes player profiles, game records, and other public information via standardized interfaces. This makes it easy for AI assistants to search, analyze, and retrieve Chess.com information without custom integrations.

How to use

Connect to the MCP server using your MCP client of choice. You have two straightforward options: run the server via Docker for a quick start or run it directly with UV for a lightweight, local setup.

How to install

Prerequisites you need before starting: a modern Docker installation or the UV tool, plus a compatible Python environment if you run the local UV workflow.

Using Docker (recommended)

1) Install Docker on your machine from Docker’s official site.

2) Add the MCP server configuration to your Claude Desktop config file.

3) Start the server via Docker using the provided configuration snippet.

Using UV

1) Install UV following the instructions for your platform.

2) Add the MCP server configuration to your Claude Desktop config file.

3) Run the server with the UV-based command shown in the configuration.

Configuration examples

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

Running with UV configuration example

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

Development

If you want to contribute, you can set up a local development environment with the UV tool, create a Python virtual environment, and install the package in editable mode. This lets you run tests and iterate on changes quickly.

Testing

Run the test suite to ensure your changes behave correctly and to prevent regressions. Install development dependencies first, then run the tests and optionally generate a coverage report.

Available tools

get_player_profile

Fetches a player's public profile from Chess.com, including username, avatar info, and basic stats.

get_player_stats

Retrieves comprehensive statistics for a given Chess.com player, covering ratings, trends, and activity.

is_player_online

Checks whether a specified Chess.com player is currently online.

get_titled_players

Returns a list of players who hold official titles recognized by Chess.com.

get_player_current_games

Gets the player's ongoing games currently active on Chess.com.

get_player_games_by_month

Fetches a player's games for a specific calendar month.

get_player_game_archives

Provides a list of available monthly game archives for a player.

download_player_games_pgn

Downloads PGN files containing all games from a specific month for a player.

get_club_profile

Retrieves information about a Chess.com club, including members and activities.

get_club_members

Lists members of a Chess.com club.