Skip to main content
Glama
stockfish-mcp

stockfish-mcp

by slothingaway

stockfish-mcp

A tiny, opinionated Model Context Protocol server that gives an LLM the best move for any chess position — powered by Stockfish.

Hand it a position as FEN or PGN (or nothing, for the starting position) and it returns the best move, the engine's evaluation, and — optionally — the predicted best line, as clean structured JSON. One tool. One call. No UCI knowledge required.

{
  "turn": "black",
  "bestmove": { "uci": "f6e4", "san": "Nxe4" },
  "ponder":   { "uci": "d2d4", "san": "d4" },
  "score": { "type": "cp", "value": -371, "perspective": "side to move" },
  "evaluation": "White is better (+3.71)",
  "fen": "r1bqk2r/ppp2ppp/2np1n2/P3p3/1PB1P3/5N2/2PP1PPP/RNBQ1RK1 b kq - 0 7"
}

Requirements

  • Node.js ≥ 18

  • Stockfish installed and on your PATH (or point STOCKFISH_PATH at the binary). This project does not bundle Stockfish.

Install Stockfish:

# Debian / Ubuntu
sudo apt install stockfish

# macOS (Homebrew)
brew install stockfish

# or download a binary from https://stockfishchess.org/download/

Related MCP server: ChessAgine MCP

Usage

With any MCP client (Claude Desktop, etc.)

Add to your client's MCP config:

{
  "mcpServers": {
    "stockfish": {
      "command": "npx",
      "args": ["-y", "stockfish-mcp"]
    }
  }
}

Or run it from a local checkout:

{
  "mcpServers": {
    "stockfish": {
      "command": "node",
      "args": ["/path/to/stockfish-mcp/index.mjs"]
    }
  }
}

From the command line (manual testing)

npm install
npm start          # speaks MCP over stdio
npm test           # end-to-end smoke test (needs stockfish installed)

The analyze tool

Parameter

Type

Default

Description

position

string

start position

A FEN string or PGN/move list. Omit for the starting position.

depth

integer

18

Search depth in plies. Higher = stronger but slower.

movetime

integer

—

If given, search this many milliseconds instead of a fixed depth.

includeLine

boolean

false

Include the engine's predicted best line (PV) in SAN.

Response

Field

Description

turn

"white" or "black" — side to move in the given position.

bestmove

{ uci, san } — the best move (null if the position is already terminal).

ponder

{ uci, san } or null — the reply the engine expects.

score

{ type: "cp" | "mate", value, perspective: "side to move" } — raw engine score.

evaluation

Human-readable, White-perspective summary, e.g. "White is better (+3.71)", "Mate in 1 for Black", "roughly equal".

fen

The FEN actually analyzed (after PGN conversion / normalization).

line

(only with includeLine) Numbered SAN principal variation, truncated with ….

Examples

FEN (black to move):

// analyze({ "position": "r1bqk2r/ppp2ppp/2np1n2/P3p3/2B1P3/5N2/2PP1PPP/RNBQ1RK1 b kq - 0 7", "depth": 14 })
{
  "turn": "black",
  "bestmove": { "uci": "f6e4", "san": "Nxe4" },
  "ponder": { "uci": "d2d4", "san": "d4" },
  "evaluation": "White is better (+3.71)"
}

PGN:

// analyze({ "position": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6", "depth": 12 })
{
  "turn": "white",
  "bestmove": { "uci": "b5c6", "san": "Bxc6" },
  "ponder": { "uci": "d7c6", "san": "dxc6" },
  "evaluation": "White is better (+0.36)"
}

Best line + mate detection:

// analyze({ "position": "6k1/5ppp/8/8/8/8/8/R6K w - - 0 1", "includeLine": true })
{
  "turn": "white",
  "bestmove": { "uci": "a1a8", "san": "Ra8#" },
  "evaluation": "Mate in 1 for White",
  "line": "1. Ra8#"
}

Configuration

Environment variables:

Variable

Default

Description

STOCKFISH_PATH

stockfish

Path to the Stockfish binary.

STOCKFISH_TIMEOUT_MS

60000

Per-search safety timeout, in milliseconds.

STOCKFISH_DEFAULT_DEPTH

18

Search depth used when the caller omits depth.

Example:

{
  "mcpServers": {
    "stockfish": {
      "command": "npx",
      "args": ["-y", "stockfish-mcp"],
      "env": { "STOCKFISH_PATH": "/usr/games/stockfish", "STOCKFISH_DEFAULT_DEPTH": "20" }
    }
  }
}

How it works

The server spawns a fresh stockfish process for each analyze call, sends position fen … followed by go depth N (or go movetime N), reads the engine's info lines to capture the latest score and principal variation, and resolves on bestmove. Moves are converted to SAN with chess.js, which also handles PGN→FEN conversion and FEN validation.

Two UCI subtleties worth noting (both handled here): go is asynchronous, so stdin is left open and no quit is sent before the search finishes — closing the pipe would abort it. And score cp/score mate are reported from the side-to-move's perspective, so we flip them when Black is to move to produce a consistent White-perspective evaluation.

AI usage in this project

Entirely written by Qwen3.8-Preview-Max

License

MIT.

A note on Stockfish: Stockfish itself is licensed GPL-3.0. This project does not include, link against, modify, or distribute Stockfish — it only spawns a Stockfish binary that you install separately and communicates with it over the public UCI protocol via a pipe. The two are separate programs, so this wrapper is independently licensed under MIT. You are responsible for obtaining Stockfish and complying with its license.

Available Tools

1 tool
analyzeA

Analyze a chess position with the Stockfish engine and return the best move.

Accepts a position as FEN or PGN (or omit it for the starting position). Returns the best move (in both UCI and human-readable SAN), the engine's evaluation, and whose turn it is. Optionally include the engine's predicted best line.

Use this whenever you need the strongest move or an evaluation for a chess position. You do NOT need to set up the position and search separately — one call does both.

Inputs: depth, movetime, position, includeLine.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusion or overlap with other tools.

    Naming Consistency5/5

    With a single tool, naming is trivially consistent and fits a clear verb-noun pattern (analyze_? but the tool name is just 'analyze', which is appropriate).

    Tool Count3/5

    A single tool is borderline for a chess engine server; it bundles position setup and search, which works but limits flexibility (e.g., no separate depth control or multiple analysis modes).

    Completeness4/5

    The tool covers the main use case of analyzing a position with evaluation and best move. It accepts FEN/PGN, making it versatile, but lacks advanced options like depth parameter or multi-move output.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables comprehensive chess analysis through Stockfish engine integration, positional evaluation, puzzle training, game review, and access to extensive chess databases. Provides visual board rendering, interactive game viewers, and tactical puzzle training with 3+ million problems from Lichess.
      34
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to perform professional-grade chess analysis using Stockfish and optionally Leela Chess Zero, including position analysis, full game review, opening lookup, and puzzle generation.
      12 npm
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables chess analysis and move generation using the Stockfish engine via MCP tools, allowing clients to evaluate positions, get best moves, apply moves, and visualize boards.
      7
      -