Chess.com MCP Server Player Data and Game Records

Overview

This MCP (Model Context Protocol) server exposes Chess.com player profiles and public game records in a way that’s immediately useful to AI assistants and other automated tools. It collects or proxies publicly available Chess.com data and presents it as MCP-compatible resources so models can search, fetch, and incorporate player metadata and game PGNs into their context windows.

By implementing MCP semantics, the server lets developers register “search” and “fetch” style tools in an assistant workflow. That makes it straightforward to answer user questions like “show me Magnus Carlsen’s recent rapid games” or “analyze this player’s opening trends” using live, searchable chess data rather than requiring the model to memorize static facts.

Features

• Exposes player profiles (username, rating history, titles, country, avatar)
• Serves game records in PGN and structured formats (moves, result, time control)
• Searchable endpoints for players and games (by username, rating range, date range)
• MCP-compliant resource metadata so AI assistants can discover available tools
• Lightweight server suitable for local use, containerization, or deployment
• Caching and configurable server options for performance

Installation / Configuration

Prerequisites: Git and Docker are recommended. The server runs in a Node.js environment; Node 16+ is typical.

Clone the repository:

git clone https://github.com/pab1it0/chess-mcp.git
cd chess-mcp

Install dependencies (Node.js):

# using npm
npm install

# or using yarn
yarn install

Start locally:

# development
npm run dev

# production
npm start

Docker (recommended for isolation):

# build the image
docker build -t chess-mcp .

# run container on port 3000
docker run -p 3000:3000 --name chess-mcp chess-mcp

Environment variables (example)

• PORT — port to listen on (default 3000)
• CACHE_TTL — cache duration for external requests (seconds)
• LOG_LEVEL — verbosity (info, debug, warn)

You can create a .env file or pass variables via the docker run -e flag.

Available Resources

The server exposes MCP-style resources and HTTP endpoints. Example endpoints (paths may vary by release):

Example: fetch a player’s profile with curl

curl -s "http://localhost:3000/players/magnuscarlsen" | jq .

Example: fetch a PGN for a game

curl -s "http://localhost:3000/games/abcdef1234" -o game.pgn

Example MCP tool descriptor (JSON) — plug into an assistant tool registry

{
  "name": "chess_mcp_search",
  "description": "Search Chess.com players and games (MCP)",
  "uri": "http://localhost:3000/mcp/resources"
}

Use Cases

• AI-assisted player research: An assistant can query the server to compile a profile for a player (ratings over time, titles, country) and incorporate that into responses or scouting reports.
• Game retrieval for analysis: Fetch PGNs for specific games so a chess engine or model-based analyzer can compute evaluations, extract opening lines, or summarize key moments.
• Coaching and training: Automatically gather a student’s recent games to produce personalized drills or detect recurring tactical mistakes.
• Dataset assembly: Download bulk game records for building training datasets or conducting statistical analyses on openings and results.
• Tooling for commentary: Live broadcasts or recap services can pull the latest games for named players and present summaries for human commentators.

Tips for Developers

• Use the MCP resources endpoint to dynamically discover what the server exposes; this makes tool registration in assistants robust to changes.
• Cache responses on the assistant side for heavy queries (e.g., large game archives) and respect server cache headers.
• If you plan to scale, run multiple instances behind a load balancer and use a shared caching layer to reduce pressure on upstream Chess.com API calls.

GitHub: https://github.com/pab1it0/chess-mcp — consult the repository for code examples, issue tracking, and contribution guidelines.