Chess.com MCP Server
# Chess.com MCP Server
[](https://github.com/piperap/MCP-Chess.com/actions/workflows/ci.yml)
[](LICENSE)
A [Model Context Protocol][mcp] (MCP) server for Chess.com's [Published Data API][pubapi]. It lets AI assistants such as Claude look up players, stats, games and clubs, and download games as PGN.
This is a fork of [pab1it0/chess-mcp][upstream] that adds a **streamable HTTP transport with optional OAuth**, so it can be used as a remote connector (claude.ai, Gemini, any MCP client that speaks HTTP), plus a systemd unit for self-hosting.
https://github.com/user-attachments/assets/3b33361b-b604-465c-9f6a-3699b6907757
[mcp]: https://modelcontextprotocol.io/introduction/introduction
[pubapi]: https://www.chess.com/news/view/published-data-api
[upstream]: https://github.com/pab1it0/chess-mcp
## Features
- Player profiles, stats, ongoing games and monthly game archives
- Monthly games as JSON or as a multi-game PGN download
- Titled players (GM, IM, FM, …) and club profiles/members
- Input validation before any request reaches Chess.com
- Two transports: stdio for local clients, streamable HTTP for remote connectors
- Optional OAuth 2.1 resource-server mode: validates JWT access tokens from any OpenID Connect provider (tested with Keycloak)
- No Chess.com credentials needed: the API is public
## Available tools
| Tool | Description |
|---|---|
| `get_player_profile` | A player's profile |
| `get_player_stats` | A player's ratings and stats |
| `get_player_current_games` | A player's ongoing daily games |
| `get_player_games_by_month` | A player's games for a given year and month |
| `get_player_game_archives` | The months for which a player has games |
| `download_player_games_pgn` | A month of games as PGN |
| `get_titled_players` | Usernames holding a title (`GM`, `WGM`, `IM`, `WIM`, `FM`, `WFM`, `NM`, `WNM`, `CM`, `WCM`) |
| `get_club_profile` | A club's profile, by its URL id |
| `get_club_members` | A club's members |
The same data is also exposed as MCP resources: `chess://player/{username}`, `chess://player/{username}/stats`, `chess://player/{username}/games/current`, `chess://player/{username}/games/{year}/{month}`, `chess://player/{username}/games/{year}/{month}/pgn`, `chess://titled/{title}` and `chess://club/{url_id}`.
## Local use (Claude Desktop and other stdio clients)
Clone the repository and install it with [uv](https://github.com/astral-sh/uv):
```bash
git clone https://github.com/piperap/MCP-Chess.com.git
cd MCP-Chess.com
uv venv && uv pip install -e .
```
Then add the server to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%/Claude/claude_desktop_config.json` on Windows, `~/.config/Claude/claude_desktop_config.json` on Linux):
```json
{
"mcpServers": {
"chess": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/MCP-Chess.com", "run", "chess-mcp"]
}
}
}
```
> If Claude Desktop reports `spawn uv ENOENT`, use the full path to `uv` as `command`.
### Docker
```bash
docker build -t chess-mcp .
```
```json
{
"mcpServers": {
"chess": {
"command": "docker",
"args": ["run", "--rm", "-i", "chess-mcp"]
}
}
}
```
## Remote deployment (streamable HTTP)
`serve_http.py` serves the same tools over streamable HTTP at `/mcp`, with a `/health` endpoint for probes.
```bash
uv venv --python 3.12
uv pip install -c constraints.txt -e ".[oauth]"
MCP_ALLOWED_HOSTS="localhost:*,mcp.example.com" .venv/bin/python serve_http.py
```
Put it behind a TLS-terminating reverse proxy or tunnel (nginx, Caddy, Cloudflare Tunnel…) and add the public hostname to `MCP_ALLOWED_HOSTS`. A hardened systemd unit is in [`deploy/chess-mcp.service`](deploy/chess-mcp.service); it reads site settings from `/etc/chess-mcp.env` (see [`deploy/chess-mcp.env.example`](deploy/chess-mcp.env.example)).
### Configuration
| Variable | Default | Purpose |
|---|---|---|
| `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8000` | Listen address |
| `MCP_ALLOWED_HOSTS` | `localhost:*,127.0.0.1:*` | Accepted `Host` headers (DNS rebinding protection) |
| `OAUTH_ENABLED` | `false` | Require OAuth access tokens. Without it the server is open; it only exposes public data |
| `MCP_RESOURCE_URL` | — | Public MCP URL, e.g. `https://mcp.example.com/mcp`. Expected token audience. Required with OAuth |
| `OAUTH_ISSUER` | — | Expected token issuer, e.g. `https://auth.example.com/realms/example`. Required with OAuth |
| `OAUTH_ALLOWED_CLIENTS` | — | Comma-separated client ids accepted in the `azp` claim. Required with OAuth |
| `OAUTH_JWKS_URL` | `{OAUTH_ISSUER}/protocol/openid-connect/certs` | Where signing keys are fetched. Override for non-Keycloak providers or to fetch keys over a private network |
| `OAUTH_REQUIRED_GROUP` | — | If set, the token's `groups` claim must contain this group |
The server never issues tokens: it acts as an OAuth resource server and validates signature (JWKS), issuer, audience, client and group. If `OAUTH_ENABLED=true` and a required variable is missing, it refuses to start.
### Keycloak example
1. Create a confidential client (e.g. `claude-chess-mcp`) with PKCE S256 and these redirect URIs:
- claude.ai: `https://claude.ai/api/mcp/auth_callback` and `https://claude.com/api/mcp/auth_callback`
- Gemini custom MCP connectors: `https://oauth-redirect.googleusercontent.com/r/*`
2. Add an audience mapper that puts `MCP_RESOURCE_URL` in access tokens.
3. claude.ai requests every scope the realm advertises, so assign the realm's client scopes to the client (as optional) or login fails with `invalid_scope`.
4. To restrict access to some users, add a group membership mapper (claim name `groups`, "Full group path" off) and set `OAUTH_REQUIRED_GROUP`.
5. In claude.ai, add a custom connector with the public `/mcp` URL, choose "use your own OAuth client" and enter the client id and secret.
## Development
```bash
uv venv
uv pip install -c constraints.txt -e ".[dev,oauth]"
pytest --cov
```
CI runs the tests on Python 3.10–3.13 and builds the Docker image on every push and pull request. Contributions are welcome: open an issue or a pull request.
> `mcp` is pinned below 2.0 because mcp 2.x removed `FastMCP`.
## Acknowledgements
Based on [chess-mcp][upstream] by Pavel Shklovsky. Uses Chess.com's [Published Data API][pubapi]; this project is not affiliated with Chess.com.
## License
[MIT](LICENSE)
TDQS
Scored across 9 tools
Most tools target clearly distinct resources: player profile, stats, current games, archives, clubs. The only mild overlap is get_player_games_by_month versus download_player_games_pgn, both scoped to a month's games, but the descriptions distinguish JSON data vs PGN file download.
All names are snake_case verb_noun with a uniform get_ prefix except the single download_player_games_pgn. The deviation is meaningful and readable, but it is still a break from the otherwise uniform pattern.
9 tools is squarely in the well-scoped range, with each tool mapping to a distinct Chess.com read endpoint. No filler or trivially redundant entries.
Player, game history, archives, PGN export, and club data are well covered, giving a coherent read-only surface. Gaps remain: no player search by name (only titled players), no single-game lookup, and no tournament or puzzle endpoints.