Chess.com Mcp Server

What is Chess MCP?

Chess MCP is a Model Context Protocol server designed to interface with Chess.com's Published Data API. It provides a standardized way to access a wealth of chess-related data, including player statistics, game records, and other public information. This allows developers and AI assistants to efficiently search and analyze chess information, making it easier to build applications and tools that leverage chess data.

Features of Chess MCP

• Standardized Interfaces: Chess MCP utilizes standardized Model Context Protocol interfaces, ensuring consistent access to data across different applications.
• Comprehensive Data Access: Users can retrieve detailed player data, including rankings, game history, and performance metrics.
• AI Integration: The protocol is designed to facilitate the integration of AI assistants, enabling them to analyze chess information and provide insights.
• Public Information: All data accessed through Chess MCP is publicly available, ensuring transparency and accessibility for developers and users alike.
• Open Source: Chess MCP is an open-source project, allowing developers to contribute, modify, and enhance the protocol as needed.

How to Use Chess MCP

1. Set Up the Environment: Ensure you have the necessary tools and libraries installed to interact with the Chess.com API.
2. Access the API: Use the standardized MCP interfaces to connect to the Chess.com data. This typically involves making HTTP requests to the API endpoints.
3. Retrieve Data: Utilize the various endpoints to fetch player data, game records, and other relevant information.
4. Analyze Data: Implement logic in your application to analyze the retrieved data, whether for personal use, AI training, or other purposes.
5. Contribute to the Project: If you have improvements or features to add, consider contributing to the Chess MCP repository on GitHub.

Frequently Asked Questions

Q: What kind of data can I access with Chess MCP?

A: You can access a variety of chess-related data, including player profiles, game histories, and statistics from Chess.com.

Q: Is Chess MCP free to use?

A: Yes, Chess MCP is an open-source project, and all data accessed through it is publicly available.

Q: Can I integrate Chess MCP with AI applications?

A: Absolutely! Chess MCP is designed to facilitate AI integration, allowing AI assistants to analyze and provide insights based on chess data.

Q: How can I contribute to Chess MCP?

A: You can contribute by forking the repository on GitHub, making your changes, and submitting a pull request for review.

Q: Where can I find the documentation for Chess MCP?

A: Documentation is typically available in the repository's README file or a dedicated documentation section within the project.

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.

Usage

Docker (Recommended)

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