Stockfish MCP Server

A local Model Context Protocol (MCP) server that exposes the Stockfish chess engine to any MCP client (Claude Desktop, Claude Code, Cline, Continue, your own client, …).

It speaks MCP over stdio. All tools are stateless — every call takes a FEN string, so the server holds no game state.

---

Tools

Tool	Purpose
analyze_position	Evaluate a position; returns score (White POV), best move, and principal variation(s). Supports multipv, depth, or movetime_ms.
get_best_move	Pick a move for the side to move. Optional skill_level (0–20) or elo (~1320–3190) to play at reduced strength.
evaluate_position	Lighter/faster single-line evaluation.
apply_moves	Play a sequence of SAN/UCI moves and return the resulting FEN.
get_legal_moves	List all legal moves (SAN + UCI).
visualize_board	Render a position as a Unicode/ASCII board.
engine_info	Engine name/version and default options.

Every tool defaults to the standard starting position when fen is omitted. Scores are from White's point of view; mate is reported as #±N.

---

Dependencies

Dependency	Version	Why
Python	≥ 3.14	Runtime (see .python-version).
python-chess (chess)	≥ 1.11.2	Board logic + UCI engine driver.
FastMCP (fastmcp)	≥ 3.4.2	MCP server framework.
Stockfish binary	17/18+	The engine itself. Not bundled (it is >100 MB); download it — see below.

Python deps are declared in pyproject.toml and pinned in uv.lock. uv is the recommended installer/runner, but plain pip/venv works too.

---

Install

# 1. Get the code
git clone <this-repo-url>
cd stockfish-mcp-server

# 2. Get the Stockfish engine binary (NOT in git — too large).
#    This downloads it to engine/stockfish:
./engine/download-stockfish.sh
#    ...or set SF_ASSET to match your CPU/OS, e.g.:
#    SF_ASSET=stockfish-ubuntu-x86-64-avx512 ./engine/download-stockfish.sh
#    Browse builds: https://github.com/official-stockfish/Stockfish/releases/latest
#    Already have Stockfish? Skip this and set STOCKFISH_PATH (see Configuration).

# 3a. Install dependencies with uv (recommended)
uv sync

# 3b. ...or with pip
python -m venv .venv && . .venv/bin/activate
pip install "chess>=1.11.2" "fastmcp>=3.4.2"

Optional: install as a command

The project is packaged with a stockfish-mcp console-script entry point:

uv tool install .        # puts `stockfish-mcp` on your PATH (~/.local/bin)
# or: pip install .

---

Run

uv run python server.py     # run the stdio server (uv)
# or, if installed as a command:
stockfish-mcp

The server communicates over stdio and is normally launched by your MCP client (below), not by hand. Stop it with Ctrl-C / SIGTERM.

---

Use it with an MCP client

MCP stdio clients launch the server as a subprocess. Point your client at either uv run python /abs/path/to/server.py or the installed stockfish-mcp command, and set STOCKFISH_PATH if the binary isn't at engine/stockfish.

A ready-to-edit example is in examples/mcp-config.json.

Generic MCP config (the shape most clients accept — e.g. a mcpServers map in Claude Desktop's claude_desktop_config.json, or .mcp.json):

{
  "mcpServers": {
    "stockfish": {
      "command": "uv",
      "args": ["run", "python", "/abs/path/to/stockfish-mcp-server/server.py"],
      "env": {
        "STOCKFISH_PATH": "/abs/path/to/stockfish-mcp-server/engine/stockfish"
      }
    }
  }
}

If you installed the command (uv tool install .), use it directly:

{
  "mcpServers": {
    "stockfish": {
      "command": "stockfish-mcp",
      "env": { "STOCKFISH_PATH": "/abs/path/to/engine/stockfish" }
    }
  }
}

Claude Code (CLI) — register in user scope so it's available everywhere:

claude mcp add stockfish -s user \
  -e STOCKFISH_PATH=/abs/path/to/engine/stockfish \
  -- stockfish-mcp
claude mcp list      # should show: stockfish … ✔ Connected

Then ask the model things like "analyze this FEN at depth 20" or "play a move against me at 1500 Elo."

Tip: launching the executable directly (the installed stockfish-mcp, or the venv's python) rather than via a wrapper makes the server the client's direct child process, so its shutdown signal handling works cleanly.

---

Configuration (environment variables)

Variable	Default	Meaning
STOCKFISH_PATH	engine/stockfish (next to server.py)	Path to the Stockfish binary.
STOCKFISH_THREADS	min(4, ncpu)	Search threads.
STOCKFISH_HASH_MB	256	Transposition-table size (MB).

Per-call search cost is capped (depth ≤ 30, movetime ≤ 60 s, multipv ≤ 10) so a single request can't stall the stdio loop.

---

Test

uv run python test_server.py    # end-to-end smoke test via an in-memory MCP client

It lists the tools and exercises analysis, mate detection, reduced-strength play, move application, and error handling — no external MCP client needed.

---

Files

server.py                 The MCP server (FastMCP + python-chess)
test_server.py            End-to-end smoke test
pyproject.toml            Package metadata + dependencies (entry point: stockfish-mcp)
uv.lock                   Pinned dependency versions
.python-version           Python version (3.14)
engine/
  download-stockfish.sh   Fetches the engine binary (binary itself is gitignored)
  LICENSE-stockfish.txt   Stockfish license (GPLv3)

---

References

• Model Context Protocol — https://modelcontextprotocol.io
• FastMCP — https://gofastmcp.com/
• python-chess — https://python-chess.readthedocs.io/
• Stockfish — https://stockfishchess.org/ · releases: https://github.com/official-stockfish/Stockfish/releases/latest
• uv — https://docs.astral.sh/uv/

---

License

This server's code is provided as-is. Stockfish is licensed under GPLv3 — see engine/LICENSE-stockfish.txt. If you redistribute the Stockfish binary, you must comply with the GPLv3 (including providing source).