# Chess.com MCP

TypeScript MCP server backed by [`chess-web-api`](https://github.com/andyruwruw/chess-web-api).

> This is an unofficial MCP server. It is not affiliated with, endorsed by, or maintained by Chess.com.

## Requirements

- Node.js 20 or newer
- npm

## Development

```bash
npm install
npm run dev
```

Build and run the compiled server:

```bash
npm run build
npm start
```

Run a local end-to-end smoke test. It verifies that all official tools are registered, starts the compiled MCP server, and exercises representative JSON and PGN responses against Chess.com.

```bash
npm run test:smoke
```

## MCP client configuration

Build the project, then add the server to an MCP client configuration.

```json
{
  "mcpServers": {
    "chesscom": {
      "command": "npx",
      "args": ["-y", "chesscom-mcp@latest"]
    }
  }
}
```

## Tools

Player:

- `get_player_profile`
- `get_player_stats`
- `get_player_current_daily_games`
- `get_player_to_move_daily_games`
- `get_player_archives`
- `get_player_games`
- `get_player_monthly_pgn`
- `get_player_clubs`
- `get_player_matches`
- `get_player_tournaments`
- `get_titled_players`

Clubs and tournaments:

- `get_club`
- `get_club_members`
- `get_club_matches`
- `get_tournament`
- `get_tournament_round`
- `get_tournament_round_group`

Team matches:

- `get_team_match`
- `get_team_match_board`
- `get_live_team_match`
- `get_live_team_match_board`

Countries:

- `get_country`
- `get_country_players`
- `get_country_clubs`

General:

- `get_daily_puzzle`
- `get_random_puzzle`
- `get_streamers`
- `get_leaderboards`

Unofficial:

- `get_game_by_id`: retrieves live game data and reconstructs PGN using Chess.com's undocumented website callback

`get_game_by_id` is not part of Chess.com's Published Data API. It may change or stop working without notice, and excessive requests may result in an IP ban. Use it sparingly.

Deprecated `getPlayerOnline` remains excluded.

Chess.com's public API limits parallel requests. This server serializes API calls to reduce `429 Too Many Requests` responses.