Chess Mcp

♟️ Chess MCP

[](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/)

An advanced Model Context Protocol (MCP) server that supercharges AI assistants with deep chess knowledge, analysis, and interactive gameplay.

By integrating Stockfish engine evaluations, popular chess APIs (Chess.com, Lichess), and visual board rendering, this server transforms an AI agent into a fully-fledged chess coach, analyst, and opponent.

✨ Key Features

• 🎮 Interactive Gameplay: Play full, interactive chess games directly against Stockfish inside your AI chat window with a dynamic, rendered board.
• 🧠 Deep Engine Analysis: Leverage Stockfish to evaluate positions, find candidate lines, and conduct comprehensive, move-by-move game reviews.
• 📊 Player Insights & Analytics: Fetch recent games from Chess.com or Lichess. Generate performance trends, batch-analyze opening win rates, and track blunder statistics.
• 🧩 Custom Puzzle Generation: Auto-extract tactical mistakes from your own games to create personalized spaced-repetition training puzzles.
• 🎨 Visual Board Rendering: Render beautiful chess board positions, highlight specific squares, draw analytical arrows, and even generate move animations (GIFs/PNG frames).

🛠️ Available MCP Tools

The server exposes a rich set of tools to the AI:

Gameplay & Rendering

• play_game: Play a full game of chess interactively against Stockfish. Returns a rich, interactive UI board.
• render_position: Render a specific chess position (FEN) to a PNG diagram with custom arrows and highlights.
• render_animation: Animate a sequence of moves (from PGN or SAN) into a GIF or frame sequence.
• get_game_state / resume_game: Access ongoing game state and seamlessly resume the interactive UI.

Analysis & Engines

• analyze_position: Get precise Stockfish evaluation and top lines for a single FEN position.
• analyze_game: Review a complete PGN move-by-move, classifying blunders, calculating accuracy, identifying openings, and pinpointing critical moments.
• identify_opening: Identify the ECO opening name for a game and report where it left known theory.

Player Accounts & Stats

• get_chesscom_games / get_lichess_games: Fetch recent games for a specific user from Chess.com or Lichess.
• batch_analyze_games: Analyze a batch of games to aggregate stats (e.g., win rate by opening, time control).
• get_performance_trends: Correlate losing streaks with specific time controls, openings, or other factors.
• generate_puzzles: Auto-extract missed tactics from user games.

🚀 Installation & Setup

Prerequisites

• Node.js (v18 or higher recommended)
• A local installation of Stockfish (make sure it's in your PATH or provide its path via ENV).
• A compatible MCP client (e.g., Claude Desktop, Antigravity IDE).

Build Instructions

# Clone the repository
git clone https://github.com/yourusername/chess_mcp.git
cd chess_mcp

# Install server dependencies
npm install

# Build the frontend UI bundle
npm run build:ui

# Build the MCP server
npm run build

⚙️ Configuration

You can configure the server using the following environment variables:

| Variable | Description | Default | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------- | | STOCKFISH_PATH | Absolute path to the Stockfish executable. If omitted, the server will try to locate it in standard paths or your system's PATH. | Auto-detected | | CHESSCOM_USERNAME | Default Chess.com username for fetching games. | null | | LICHESS_USERNAME | Default Lichess username for fetching games. | null | | CHESS_MCP_THREADS | Number of CPU threads allocated to Stockfish. | CPU Count - 2 | | CHESS_MCP_HASH_MB | Hash memory in MB allocated to Stockfish. | 128 | | CHESS_MCP_MOVE_TIME_MS | Default engine thinking time (ms) per move during full game analysis. | 150 |

💻 Usage

To run the MCP server manually (for testing or directly passing to an MCP client via stdio):

npm start

Adding to Claude Desktop (or other MCP clients)

Add the following to your MCP configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "chess": {
      "command": "node",
      "args": ["/absolute/path/to/chess_mcp/dist/server.js"],
      "env": {
        "CHESSCOM_USERNAME": "your_username",
        "LICHESS_USERNAME": "your_username"
      }
    }
  }
}

(Make sure to replace the args with the actual absolute path to the built server.js file.)

🏗️ Technologies Used

• Model Context Protocol (MCP) - For AI-tool integration
• TypeScript & Node.js - Core server environment
• Vite & Vanilla TS - Fast, lightweight interactive frontend
• Chess.js - Move validation and game logic
• Stockfish - World-class chess engine integration

📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: realsidg
• Source: realsidg/chess_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.