MCP Chess.com Server

A Model Context Protocol (MCP) server that provides access to Chess.com's public API, allowing AI assistants to fetch player information and statistics.

Features

• Player Information: Get detailed player profiles including usernames, ratings, and account information
• Player Statistics: Retrieve comprehensive game statistics including ratings across different time controls
• MCP Integration: Seamlessly integrates with MCP-compatible AI assistants like Claude

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended) or pip

Setup Instructions

1. Initialize the project:

   uv init
   

2. Create and activate virtual environment:

   uv venv
   .\.venv\Scripts\activate  # Windows
   # or
   source .venv/bin/activate  # Linux/macOS
   

3. Install dependencies:

   uv add mcp[cli]
   uv sync
   

4. Test the server:

   uv run chess
   

Project Structure

mcp-server-chess-com/
├── src/
│   └── chess/
│       ├── __init__.py
│       ├── chess_api.py      # Chess.com API client
│       └── server.py         # MCP server implementation
├── pyproject.toml            # Project configuration
├── uv.lock                   # Dependency lock file
└── README.md                 # This file

Configuration

MCP Client Setup (Claude/Cline)

To use this server with Claude via Cline, update your MCP settings:

1. Locate the MCP settings file:

   • Path: ~/.config/claude-desktop/claude_desktop_config.json (macOS/Linux)
   • Path: %APPDATA%\Claude\claude_desktop_config.json (Windows)
   • Or for Cline: cline_mcp_settings.json

2. Add the server configuration:

   {
     "mcpServers": {
       "server": {
         "command": "uv",
         "args": [
           "--directory",
           "BASE_PATH_TO_MCP_PROJECT\\mcp-server-chess-com",
           "run",
           "chess"
         ]
       }
     }
   }
   

   Note: Replace BASE_PATH_TO_MCP_PROJECT with the actual path to your project directory.

3. Restart your MCP client to load the new server.

4. Verify the server is loaded: After restarting, you should see the server listed in your MCP Servers panel as shown below:

   

   The server should appear as "server" with a green status indicator, showing it's successfully connected and ready to use.

Usage

Once configured, you can interact with the Chess.com API through your MCP client:

Available Tools

get_chess_player_info

Retrieves basic player information.

Parameters:

• username (string): Chess.com username

Example queries:

• "What is the player details for Hikaru?"
• "Get information about Magnus Carlsen's Chess.com profile"
• "Show me details for the player 'GMHikaru'"

get_chess_player_stats

Retrieves detailed player statistics including ratings.

Parameters:

• username (string): Chess.com username

Example queries:

• "What are Hikaru's current ratings?"
• "Show me Magnus Carlsen's chess statistics"
• "Get the rating statistics for player 'GMHikaru'"

Sample Interactions

Here's an example of how the MCP server works in practice:

The screenshot above shows a real interaction where:

• User Query: "What is the player details for Hikaru?"
• MCP Tool Called: get_chess_player_info
• Arguments: {"username": "GMHikaru"}
• Response: Complete player profile data from Chess.com
• Token Usage: Shows input/output tokens and cost per interaction
• Performance: Demonstrates real-time API response with detailed player information

User: "What is the player details for Hikaru?"
Assistant: [Calls get_chess_player_info with username "GMHikaru"]

User: "What are Magnus Carlsen's current ratings?"
Assistant: [Calls get_chess_player_stats with username "MagnusCarlsen"]

API Reference

Chess.com API Endpoints Used

• Player Profile: https://api.chess.com/pub/player/{username}
• Player Stats: https://api.chess.com/pub/player/{username}/stats

Response Format

The server returns JSON data directly from Chess.com's API, including:

Player Info Response:

• Player details (username, title, followers, etc.)
• Account status and verification
• Profile URLs and avatars

Player Stats Response:

• Current ratings for different time controls (bullet, blitz, rapid, daily)
• Game statistics (wins, losses, draws)
• Performance metrics

Development

Building the Project

# Install in development mode
uv sync

# Run the server
uv run chess

# Run with debugging
uv run chess --debug

Project Configuration

The project uses the following key configurations in pyproject.toml:

[project]
name = "mcp-server-chess-com"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "mcp[cli]>=1.13.1",
    "requests>=2.25.0",
]

[project.scripts]
chess = "chess.server:main"

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
package-dir= {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]

Dependencies

• mcp[cli] (>=1.13.1): Model Context Protocol framework
• requests (>=2.25.0): HTTP client for Chess.com API calls

Error Handling

The server includes robust error handling for:

• Invalid usernames
• API rate limiting
• Network connectivity issues
• Chess.com API downtime

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Chess.com for providing the public API
• The MCP community for the excellent protocol and tools
• FastMCP for simplifying MCP server development

Support

For issues and questions:

• Check Chess.com's API documentation: https://www.chess.com/news/view/published-data-api
• Review MCP documentation: https://spec.modelcontextprotocol.io/
• Open an issue in this repository