Chess.com MCP Server

1# Chess.com MCP Server
2 
3A [Model Context Protocol][mcp] (MCP) server for Chess.com's Published Data API.
4 
5This 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.
6 
7https://github.com/user-attachments/assets/3b33361b-b604-465c-9f6a-3699b6907757
8 
9[mcp]: https://modelcontextprotocol.io/introduction/introduction
10 
11## Features
12 
13- [x] Access player profiles, stats, and game records
14- [x] Search games by date and player
15- [x] Check player online status
16- [x] Get information about clubs and titled players
17- [x] No authentication required (uses Chess.com's public API)
18- [x] Docker containerization support
19- [x] Provide interactive tools for AI assistants
20 
21The list of tools is configurable, so you can choose which tools you want to make available to the MCP client.
22 
23## Usage
24 
25### Docker (Recommended)
26 
27The easiest way to run chess-mcp with [Claude Desktop](https://claude.ai/desktop) is using Docker. If you don't have Docker installed, you can get it from [Docker's official website](https://www.docker.com/get-started/).
28 
29 
30Edit your Claude Desktop config file:
31* Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
32* Windows: `%APPDATA%/Claude/claude_desktop_config.json`
33* Linux: `~/.config/Claude/claude_desktop_config.json`
34 
35Then add the following configuration:
36 
37```json
38{
39  "mcpServers": {
40    "chess": {
41      "command": "docker",
42      "args": [
43        "run",
44        "--rm",
45        "-i",
46        "pab1it0/chess-mcp"
47      ]
48    }
49  }
50}
51```
52 
53### Running with UV
54 
55Alternatively, you can run the server directly using UV. Edit your Claude Desktop config file (locations listed above) and add the server configuration:
56 
57```json
58{
59  "mcpServers": {
60    "chess": {
61      "command": "uv",
62      "args": [
63        "--directory",
64        "<full path to chess-mcp directory>",
65        "run",
66        "src/chess_mcp/main.py"
67      ]
68    }
69  }
70}
71```
72 
73> Note: if you see `Error: spawn uv ENOENT` in [Claude Desktop](https://claude.ai/desktop), you may need to specify the full path to `uv` or set the environment variable `NO_UV=1` in the configuration.
74 
75## Development
76 
77Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.
78 
79This project uses [`uv`](https://github.com/astral-sh/uv) to manage dependencies. Install `uv` following the instructions for your platform:
80 
81```bash
82curl -LsSf https://astral.sh/uv/install.sh | sh
83```
84 
85You can then create a virtual environment and install the dependencies with:
86 
87```bash
88uv venv
89source .venv/bin/activate  # On Unix/macOS
90.venv\Scripts\activate     # On Windows
91uv pip install -e .
92```
93 
94### Testing
95 
96The project includes a test suite that ensures functionality and helps prevent regressions.
97 
98Run the tests with pytest:
99 
100```bash
101# Install development dependencies
102uv pip install -e ".[dev]"
103 
104# Run the tests
105pytest
106 
107# Run with coverage report
108pytest --cov=src --cov-report=term-missing
109```
110 
111## Available Tools
112 
113### Player Information
114- `get_player_profile` - Get a player's profile from Chess.com
115- `get_player_stats` - Get a player's stats from Chess.com
116- `is_player_online` - Check if a player is currently online on Chess.com
117- `get_titled_players` - Get a list of titled players from Chess.com
118 
119### Games
120- `get_player_current_games` - Get a player's ongoing games on Chess.com
121- `get_player_games_by_month` - Get a player's games for a specific month from Chess.com
122- `get_player_game_archives` - Get a list of available monthly game archives for a player on Chess.com
123- `download_player_games_pgn` - Download PGN files for all games in a specific month from Chess.com
124 
125### Clubs
126- `get_club_profile` - Get information about a club on Chess.com
127- `get_club_members` - Get members of a club on Chess.com
128 
129## License
130 
131MIT
132 
133---
134 
135[mcp]: https://modelcontextprotocol.io