Chess Engine MCP Server

A Model Context Protocol (MCP) server providing AI assistants with professional-grade chess analysis using Stockfish (alpha-beta) and optionally Leela Chess Zero / Lc0 (neural network). Both engines share the same tool interface and run side-by-side when Lc0 is configured.

Features

Stockfish tools (always available)

| Tool | Description | |------|-------------| | sf_analyse_position | Analyse any position (FEN → evaluation + best moves + top lines) | | sf_analyse_game | Full game analysis (PGN → move-by-move eval, accuracy %, error counts) | | sf_lookup_opening | Search opening database by name or ECO code | | sf_identify_opening | Identify the opening from moves or PGN | | sf_generate_puzzle | Generate tactic puzzles from positions |

Lc0 tools (enabled when LC0_WEIGHTS_PATH is set)

| Tool | Description | |------|-------------| | lc0_analyse_position | Analyse a position with the Lc0 neural network | | lc0_analyse_game | Full game analysis using Lc0 evaluation | | lc0_generate_puzzle | Generate tactic puzzles using Lc0's evaluation |

Quick Start

Option 1: Docker (recommended)

# Published image (Stockfish + Lc0 + Maia-1900 baked in; linux/amd64 + arm64)
docker run -i ghcr.io/alegerber/stockfish-lc0-mcp:latest

# …or build it yourself — Stockfish only
docker build -t stockfish-lc0-mcp .
docker run -i stockfish-lc0-mcp

# With Lc0 (mount weights file)
docker run -i \
  -e LC0_WEIGHTS_PATH=/weights/lc0.pb.gz \
  -v /path/to/weights:/weights \
  stockfish-lc0-mcp

# Or with docker compose
docker compose up --build

Option 2: npm (npx)

Prerequisites: Node.js 22+ and a locally installed Stockfish — see the install commands under Option 3. The npm package does not bundle the engines — the Docker image does.

npx stockfish-lc0-mcp

Option 3: Local Node.js (from source)

Prerequisites: Node.js 22+ (CI-tested on LTS 22, 24, 26), Stockfish binary installed.

# Install Stockfish
# macOS:  brew install stockfish
# Ubuntu: sudo apt install stockfish
# Windows: download from https://stockfishchess.org/download/

# Install dependencies and build
npm install
npm run build

# Run (Stockfish only)
npm start

# Run with Lc0
LC0_WEIGHTS_PATH=/path/to/lc0.pb.gz npm start

Configuration

Stockfish environment variables

| Variable | Default | Description | |----------|---------|-------------| | STOCKFISH_PATH | stockfish | Path to the Stockfish binary | | STOCKFISH_THREADS | 2 | Number of CPU threads | | STOCKFISH_HASH | 128 | Hash table size in MB |

Lc0 environment variables

| Variable | Default | Description | |----------|---------|-------------| | LC0_WEIGHTS_PATH | (unset) | Path to a .pb.gz weights file — required to enable Lc0 | | LC0_PATH | lc0 | Path to the Lc0 binary | | LC0_BACKEND | (auto) | Lc0 backend: cuda, metal, cpu, etc. | | LC0_THREADS | 2 | Number of CPU threads for Lc0 | | LC0_HASH | 128 | Hash table size in MB for Lc0 |

Note: The depth parameter for Lc0 tools is mapped internally to node counts via an exponential table (100 nodes at depth 1 → 1 000 000 nodes at depth 30), since MCTS depth is not comparable to alpha-beta depth.

Claude Desktop Integration

Add to your claude_desktop_config.json:

Docker (Stockfish only)

{
  "mcpServers": {
    "chess": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "stockfish-lc0-mcp"]
    }
  }
}

Docker (Stockfish + Lc0)

{
  "mcpServers": {
    "chess": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "LC0_WEIGHTS_PATH=/weights/lc0.pb.gz",
        "-v", "/path/to/weights:/weights",
        "stockfish-lc0-mcp"
      ]
    }
  }
}

npm (npx)

Requires a locally installed Stockfish (see Quick Start). Set STOCKFISH_PATH explicitly: GUI-launched clients (e.g. Claude Desktop on macOS) don't inherit your shell's PATH, so a bare stockfish lookup can fail even though brew install stockfish succeeded.

{
  "mcpServers": {
    "chess": {
      "command": "npx",
      "args": ["-y", "stockfish-lc0-mcp"],
      "env": {
        "STOCKFISH_PATH": "/opt/homebrew/bin/stockfish"
      }
    }
  }
}

Local Node.js

{
  "mcpServers": {
    "chess": {
      "command": "node",
      "args": ["/path/to/stockfish-lc0-mcp/dist/index.js"],
      "env": {
        "STOCKFISH_PATH": "stockfish",
        "STOCKFISH_THREADS": "2",
        "STOCKFISH_HASH": "256",
        "LC0_PATH": "lc0",
        "LC0_WEIGHTS_PATH": "/path/to/lc0.pb.gz"
      }
    }
  }
}

Usage Examples

Stockfish

"Analyse this position: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1"

"Review this game: 1. e4 e5 2. Qh5 Nc6 3. Nf3 g6 4. Qh4 Be7 ..."

"What is the Wayward Queen Attack?"

"What opening is 1. e4 e5 2. Nf3 Nc6 3. Bc4?"

"Create a tactic puzzle from this position: [FEN]"

Lc0

"What does the neural network think of this position?"

"Analyse this game with Lc0 and compare with Stockfish: 1. e4 e5 ..."

"Find tactics using Lc0 in this position: [FEN]"

Architecture

src/
├── index.ts              # MCP server entry, tool registration (Stockfish + Lc0)
├── types.ts              # TypeScript interfaces (UciEngine, UciLine, UciScore, …)
├── constants.ts          # Thresholds, defaults, LC0_DEPTH_TO_NODES mapping
├── schemas/
│   └── index.ts          # Zod input validation schemas
├── services/
│   ├── engine.ts         # BaseUciEngine, StockfishEngine, Lc0Engine
│   ├── chess-utils.ts    # chess.js wrapper (PGN/FEN/SAN/openings)
│   └── formatting.ts     # Markdown output formatting
└── tools/
    ├── analyse-position.ts  # Single position analysis
    ├── analyse-game.ts      # Full game analysis + accuracy model
    ├── openings.ts          # Opening lookup & identification
    └── puzzle.ts            # Tactic puzzle generation

Both engines implement the UciEngine interface and are interchangeable at the tool layer — all tool functions accept a UciEngine parameter, so sf_* and lc0_* tools share identical logic with different engine instances.

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript → dist/
npm test             # Run unit tests (Vitest, 150+ tests)
npm run lint         # ESLint

License

MIT