MCP Stockfish

What sonirico/mcp-stockfish MCP server does

The sonirico/mcp-stockfish MCP server provides an MCP bridge to a locally available Stockfish chess engine. An AI client sends a UCI command through the exposed MCP tool, and the server returns Stockfish's response in a JSON object containing the status, session ID, original command, response lines, and any error details.

The tool accepts two parameters:

• command: The UCI command to execute.
• session_id: An optional identifier for an existing engine session. If omitted, the server creates one.

The server supports multiple concurrent sessions. Each session starts a Stockfish process when needed, preserves UCI state between commands, and is cleaned up when finished or when its timeout is reached.

How it works

The server launches Stockfish as a separate process and communicates with it using the Universal Chess Interface. Commands can initialize the engine, check readiness, set a starting position or FEN position, start a search, stop a search, or close a session.

Documented examples include uci, isready, position startpos, position fen [FEN], go, go depth [n], go movetime [ms], stop, and quit. Because the tool accepts a UCI command string, the engine interaction is stateful within each session rather than limited to one isolated request.

The default MCP transport is stdio. An HTTP server mode is also available through configuration, with host and port settings. The implementation uses the Go MCP SDK from mark3labs/mcp-go.

Setup and configuration

The repository's quick-start instructions clone the project, enter its directory, and run make install. After installation, start the executable with mcp-stockfish. Stockfish must be available as stockfish on the executable path unless MCP_STOCKFISH_PATH points to a different binary.

The sonirico/mcp-stockfish MCP server uses stdio by default. Set MCP_STOCKFISH_SERVER_MODE=http to select HTTP mode. HTTP host and port default to localhost and 8080 and can be changed with MCP_STOCKFISH_HTTP_HOST and MCP_STOCKFISH_HTTP_PORT.

Session behavior can be adjusted with MCP_STOCKFISH_MAX_SESSIONS, MCP_STOCKFISH_SESSION_TIMEOUT, and MCP_STOCKFISH_COMMAND_TIMEOUT. Logging supports configurable level, format, and output destination through the corresponding MCP_STOCKFISH_LOG_* variables.

Tools and capabilities

• Send UCI commands to Stockfish.
• Analyze the standard starting position or a position supplied in FEN notation.
• Request searches by depth or by a fixed time in milliseconds.
• Keep engine state across calls within a session.
• Run several Stockfish sessions concurrently.
• Return structured JSON results and errors.
• Use stdio or configured HTTP server mode.

Limitations and notes

The server is a bridge around Stockfish; the README does not describe a separate chess notation, board-management, or move-validation API beyond the UCI command tool. Stockfish availability is therefore part of the local setup, and the binary path may need configuration.

The documented default session limit is 10, with a 30-minute session timeout and a 30-second command timeout. These settings may affect long-running or highly concurrent analysis workloads. The README shows Claude Desktop configuration, but does not provide compatibility details for other MCP clients.

The project is licensed under MIT. The sonirico/mcp-stockfish MCP server itself does not list API credentials or external authentication requirements.