# Chess Mcp

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-realsidg-chess-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [realsidg](https://agentstack.voostack.com/s/realsidg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [realsidg](https://github.com/realsidg)
- **Source:** https://github.com/realsidg/chess_mcp

## Install

```sh
agentstack add mcp-realsidg-chess-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ♟️ Chess MCP

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

An advanced [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://stockfishchess.org/) (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

```bash
# 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):

```bash
npm start
```

### Adding to Claude Desktop (or other MCP clients)

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

```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)](https://modelcontextprotocol.io/)** - For AI-tool integration
- **[TypeScript](https://www.typescriptlang.org/) & [Node.js](https://nodejs.org/)** - Core server environment
- **[Vite](https://vitejs.dev/) & Vanilla TS** - Fast, lightweight interactive frontend
- **[Chess.js](https://github.com/jhlywa/chess.js)** - Move validation and game logic
- **[Stockfish](https://stockfishchess.org/)** - 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](https://github.com/realsidg)
- **Source:** [realsidg/chess_mcp](https://github.com/realsidg/chess_mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-realsidg-chess-mcp
- Seller: https://agentstack.voostack.com/s/realsidg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.