mcp-stockfish

mcp-stockfish exposes a bridge between a Large Language Model and the Stockfish chess engine via the MCP protocol. It supports multiple concurrent Stockfish sessions and provides a full UCI command surface (uci, isready, position startpos, position fen, go, go depth, go movetime, stop, quit). This lets your AI issue standard UCI commands and receive structured JSON responses, enabling multi-position analysis and long-running evaluations without forcing you to manage engine lifecycles manually. The server can run in stdio mode for local usage or in http mode for web-scale deployments, and it can be started with or without a custom Stockfish binary path. The tool is designed to handle concurrent sessions, maintain UCI state per session, and clean up resources when sessions timeout or are closed.

Prerequisites:

• Git
• Go installed on your system (the project is Go-based / MCP-go powered)
• Build tools (make)
• Optional: Docker if you prefer containerized usage

Install steps:

1. Clone the repository: git clone https://github.com/sonirico/mcp-stockfish cd mcp-stockfish

2. Build / install the binary using the project's Makefile: make install

3. Run in stdio mode (default): ./mcp-stockfish

4. Run in HTTP mode (if you want web-scale access): MCP_STOCKFISH_SERVER_MODE=http ./mcp-stockfish

5. If you want to customize the Stockfish binary path, export the path before starting: export MCP_STOCKFISH_PATH=/path/to/stockfish ./mcp-stockfish

6. Optional: run via container (Docker-ready): docker build -t mcp-stockfish . docker run -p 8080:8080 -e MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish

Environment variables to be aware of:

• MCP_STOCKFISH_SERVER_MODE: stdio (default) or http
• MCP_STOCKFISH_HTTP_HOST / MCP_STOCKFISH_HTTP_PORT: for HTTP mode
• MCP_STOCKFISH_PATH: path to Stockfish binary (defaults to 'stockfish')
• MCP_STOCKFISH_MAX_SESSIONS / SESSION_TIMEOUT / COMMAND_TIMEOUT: tune concurrency and timeouts
• Logging: MCP_STOCKFISH_LOG_LEVEL, MCP_STOCKFISH_LOG_FORMAT, MCP_STOCKFISH_LOG_OUTPUT

Tips:

• For HTTP mode, ensure the host/port are reachable by your clients and proxies.
• Use the env-based integration example to embed the MCP server in higher-level orchestrations.
• Monitor sessions and timeouts to prevent resource exhaustion in long-running analyses.