Stockfish MCP Server for AI Chess Integration

Overview

This repository implements a Model Context Protocol (MCP) server that exposes the Stockfish chess engine to LLMs and other AI systems. The server wraps Stockfish with MCP-compatible request/response semantics so an AI can send UCI commands, maintain long-lived analysis sessions, and receive structured JSON responses suitable for programmatic consumption.

The server supports multiple concurrent sessions, configurable timeouts and limits, and can run either over stdio (for direct MCP integrations) or as an HTTP service (for web-based orchestration). It is written in Go and built on top of mark3labs/mcp-go to handle the MCP layer cleanly.

Features

• Concurrent sessions: spawn and manage multiple Stockfish instances on demand.
• Full UCI support: send standard UCI commands (position, go, stop, isready, quit, etc.).
• Session persistence: keep UCI state between commands within a session.
• JSON-first responses: responses are returned in a structured JSON envelope for easy parsing by LLMs or microservices.
• Configurable resource limits: max sessions, per-command timeouts, session timeouts.
• Two server modes: stdio (MCP over stdin/stdout) and HTTP (JSON over HTTP).
• Docker-ready and simple build/test make targets.

Installation / Configuration

Clone, build and run:

git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make build
# run in stdio mode (default)
./mcp-stockfish

Run with a custom Stockfish binary:

MCP_STOCKFISH_PATH=/opt/stockfish/bin/stockfish ./mcp-stockfish

Run as an HTTP server:

MCP_STOCKFISH_SERVER_MODE=http MCP_STOCKFISH_HTTP_HOST=0.0.0.0 MCP_STOCKFISH_HTTP_PORT=8080 ./mcp-stockfish

Environment variables (with typical defaults):

MCP_STOCKFISH_SERVER_MODE        "stdio"        # "stdio" or "http"
MCP_STOCKFISH_HTTP_HOST         "localhost"
MCP_STOCKFISH_HTTP_PORT         8080
MCP_STOCKFISH_PATH              "stockfish"
MCP_STOCKFISH_MAX_SESSIONS      10
MCP_STOCKFISH_SESSION_TIMEOUT   "30m"
MCP_STOCKFISH_COMMAND_TIMEOUT   "30s"
MCP_STOCKFISH_LOG_LEVEL         "info"         # debug|info|warn|error|fatal
MCP_STOCKFISH_LOG_FORMAT        "console"      # json|console
MCP_STOCKFISH_LOG_OUTPUT        "stdout"       # stdout|stderr

Docker (build & run):

docker build -t mcp-stockfish .
docker run --rm -e MCP_STOCKFISH_SERVER_MODE=http -p 8080:8080 mcp-stockfish

Available Tools

Tool parameters accepted per request:

• command (string) — the UCI command to execute (required). Examples: “uci”, “isready”, “position startpos”, “go depth 10”.
• session_id (string) — optional: the session identifier. If omitted, the server will create a new session and return its ID.

Response envelope (JSON):

{
  "status": "success|error",
  "session_id": "uuid",
  "command": "uci",
  "response": ["uciok", "id name Stockfish ..."],
  "error": ""
}

Supported UCI commands (common subset):

Notes:

• The server preserves UCI state for the lifetime of a session (moves, options, position).
• Responses are returned as arrays of textual lines emitted by Stockfish so callers can parse eval strings, bestmoves, PVs, etc.

Use Cases

1. LLM-assisted move generation

   • An LLM asks the MCP server for the best move in the current game state. The LLM supplies a FEN via “position fen …” and runs “go depth 12”. The server returns the bestmove and principal variation in the JSON response for the LLM to incorporate into its reasoning or message.

2. Real-time chess analysis for agents

   • Run parallel sessions for multiple candidate positions in a planning loop. Each session maintains its own UCI state so background analysis can continue while the agent reasons about results.

3. Web integration and tooling

   • Start the server in HTTP mode behind an API gateway. A web app or microservice posts JSON requests (command + session_id) and receives parsed Stockfish output without managing engine processes directly.

Example HTTP request (HTTP mode):

curl -X POST 'http://localhost:8080/' \
  -H 'Content-Type: application/json' \
  -d '{"command":"position startpos\ngo depth