Chess

Provides real-time Chess.com player data via MCP, with profile and statistics endpoints.

python

0

GitHub Stars

python

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cyprianfusi-mcp-chess-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp_chess_server",
        "run",
        "chess.py"
      ]
    }
  }
}

You set up an MCP server that fetches real-time Chess.com player data and statistics, enabling AI assistants and clients to query player profiles and metrics efficiently. This MCP server provides robust, typed endpoints for profile lookup and stats retrieval, with clear error handling and easy integration with MCP clients like Claude Desktop.

How to use

You run the MCP server locally or in your environment and connect your MCP client to it to retrieve Chess.com data. Use the provided tools to look up a player’s public profile or fetch comprehensive statistics. The server exposes clear endpoints via MCP so your client can request data without directly handling Chess.com API calls.

Usage patterns include: looking up a player’s profile by username to obtain fields such as username, profile URL, country, location, join date, last online timestamp, followers, and more; and retrieving statistics such as current ratings across game types, win/loss/draw records, tactics rating, and puzzle-related metrics. Each request returns structured data with type hints to help your client integrate smoothly.

How to install

Prerequisites you need before starting: Python 3.13 or newer. A runtime manager such as uv is recommended, or you can use pip for package management.

# Prerequisites
python3 --version

# If you use uv (recommended)
uv sync

# Or install dependencies with pip
pip install -e .

Additional setup and configuration

Run the server directly using the MCP command or via Python module. The server can be started with either method.

Starting via the MCP command (example): the server is run from its installed location with the directory specified so MCP can locate the code.

# Start the server using the MCP command (example runtime)
uv --directory /path/to/mcp_chess_server run chess.py

Notes on integration with clients

To integrate with Clifford Desktop or similar MCP clients, configure the MCP server entry so the client can spawn or connect to the server process. You can point the client at a locally running process or use a git-based initialization as shown in the examples.

Available tools

get_chess_player_profile

Retrieves the public profile for a Chess.com player, returning fields such as username, ID, URL, name, country, location, join date, last online timestamp, followers, and more.

get_chess_player_stats

Retrieves comprehensive statistics for a Chess.com player, including current ratings across game types, best ratings, win/loss/draw records, tactics rating, lessons stats, and puzzle metrics.