Chess MCP

🚀 Chess.com MCP Server

A Model Context Protocol (MCP) server for the Chess.com data API. Through the standardized MCP interface, this server can access Chess.com's player data, game records, and other public information, allowing AI assistants to search for and analyze chess information.

Link

🚀 Quick Start

This MCP server provides a convenient way to access Chess.com's data. You can use it through Docker or directly with UV.

✨ Features

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

The list of tools is configurable, and you can choose which tools to offer to MCP clients.

📦 Installation

Docker (Recommended)

The easiest way to run chess-mcp with Claude Desktop is through Docker. If you don't have Docker installed, download and install it from the official Docker website.

Edit your Claude Desktop configuration 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"
      ]
    }
  }
}

Directly Using UV

Alternatively, you can run the server directly using UV. Edit your Claude Desktop configuration file (as described above) and add the following server configuration:

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

⚠️ Important 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.

🔧 Technical Details

This project uses uv to manage dependencies. Install uv following the platform-specific instructions:

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

Then create a virtual environment and install the dependencies:

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 to ensure functionality and prevent regressions.

Run the tests:

npm test

💻 Usage Examples

Tools

Here is a list of tools supported by the MCP server:

• get_player_profile: Get player profile information.
• search_games_by_date: Search for game records by date.
• check_online_status: Check player online status.
• get_club_info: Get detailed club information.
• retrieve_titled_players: Get a list of players with specific titles.

Each tool has detailed documentation and examples to help you easily integrate it into your project.

📚 Documentation

If you have any suggestions or improvements, please open an issue or submit a pull request.