What can you do with this server?

Analyze any chess position (FEN, PGN, or starting position) with Stockfish to get the best move in UCI and SAN, engine evaluation (raw and human-readable), whose turn it is, and optionally the principal variation in SAN. Control search depth (1-40 plies, default 18) or movetime in milliseconds. Detects checkmate/stalemate, provides ponder move, and returns normalized FEN. Configurable Stockfish binary path and default parameters via environment variables.

How do I use stockfish-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@stockfish-mcp What's the best move from the starting position?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

stockfish-mcp

by slothingaway

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

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.

ParametersJSON Schema

Name	Required	Description
`depth`	No	Search depth in plies. Higher = stronger but slower. Default 18.
`movetime`	No	If given, search for this many milliseconds instead of using a fixed depth.
`position`	No	The position to analyze, as a FEN string or a PGN (move list). Omit for the starting position.
`includeLine`	No	Include the engine's predicted best line (principal variation) in SAN. Default false.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description discloses key behaviors: returns best move, evaluation, turn, optional best line; uses Stockfish; accepts FEN/PGN; and explains depth and movetime parameters. It does not mention destructive or auth concerns, but these are likely irrelevant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences in the first paragraph plus a usage note. It is front-loaded with the core action, every sentence adds value, and there is no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no required ones, and no output schema, the description covers input formats, output items, and usage. It could mention evaluation format (centipawns or mate) but overall comprehensive for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning by explaining defaults (depth 18 plies), usage of movetime to override depth, and that position can be omitted for starting position. This enhances standalone schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes a chess position with Stockfish and returns the best move, evaluation, and turn. It specifies input formats (FEN, PGN, or omitted for start position), making the purpose specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using this tool when the strongest move or evaluation is needed, and clarifies that separate setup/search is unnecessary, providing clear context for when to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

1 tool updatev1.0.0Jul 28, 2026
- First observedanalyze

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-07-28 05:05 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

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

chess-eval A
com.x402supply
Stockfish chess eval: best move, score, principal variation, multipv. $0.005/call via x402.
Games & Gamification Entertainment & Media
22
BetterChess A
co.betterchess
Chess MCP for Claude: engine analysis, attack maps, game review. One URL, no install.
Games & Gamification
41
Lichess B
io.github.pipeworx-io
Lichess public API: players, ratings, eval, tablebase, opening explorer
Games & Gamification Sports
2
PlyMove
com.plymove
Pedagogical chess intelligence for AI agents: explain positions and games for a target Elo.
Games & Gamification Education & Learning Tools
1

Related MCP Servers

Chess Analysis Assistant
Games & Gamification
turlockmike
A
license
Not graded
quality
D
maintenance
Helps you analyze chess positions and get professional evaluations using Stockfish.
Updated 2 years ago (2025-02-04 03:10 UTC)
12 npm
19
MIT
ChessAgine MCP
Games & Gamification Knowledge & Memory Search
jalpp
A
license
Not graded
quality
A
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.
Updated 6 days ago (2026-09-15 01:11 UTC)
32
AGPL 3.0
Chess MCP Server
Games & Gamification Autonomous Agents
11hritik11
A
license
Not graded
quality
D
maintenance
Enables playing chess games with legal move validation and AI opponent moves powered by the Stockfish engine. Supports multiple concurrent games and provides moves in UCI format.
Updated 9 months ago (2025-12-31 03:11 UTC)
MIT
Chess Engine MCP Server
Games & Gamification AI & Machine Learning
alegerber
A
license
Not graded
quality
B
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.
Updated a month ago (2026-08-26 04:33 UTC)
6 npm
2
MIT

stockfish-mcp

Requirements

Usage

With any MCP client (Claude Desktop, etc.)

From the command line (manual testing)

The analyze tool

Response

Examples

Configuration

How it works

AI usage in this project

License

Available Tools

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Chess Analysis Assistant

ChessAgine MCP

Chess MCP Server

Chess Engine MCP Server

The `analyze` tool