Integrate Stockfish Chess Engine with AI Systems
MCP server bridging AI to the Stockfish chess engine, running concurrent UCI sessions for position analysis.
Why it matters
Connect AI systems to the powerful Stockfish chess engine via the Model Context Protocol. Analyze chess positions and evaluate moves with advanced AI capabilities.
Outcomes
What it gets done
Establish communication between AI and Stockfish using MCP.
Analyze chess positions and evaluate moves.
Support concurrent sessions and full UCI command set.
Configure server mode, logging, and timeouts.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-stockfish | bash Capabilities
Tools your agent gets
Initializes the engine in UCI mode
Checks engine readiness and returns readyok status
Sets the board to starting position or uses FEN notation
Runs engine to calculate best move with optional depth or time constraints
Stops the current search operation
Closes the session
Overview
Stockfish MCP Server
An MCP server bridging AI assistants to the Stockfish chess engine, exposing full UCI protocol commands for position setup, move search, and concurrent session management. Use when an AI assistant needs real Stockfish-strength position analysis or move search. Requires a Stockfish binary on the host; scoped to raw UCI protocol, not board UI or game orchestration.
What it does
mcp-stockfish is an MCP server that bridges AI systems to the Stockfish chess engine, built on the mcp-go SDK. It handles multiple concurrent Stockfish sessions, exposing full UCI (Universal Chess Interface) command support: uci (initialize UCI mode), isready (readiness check, returns readyok), position startpos or position fen [FEN] (set up a board position), go, go depth [n] (search n plies deep), and go movetime [ms] (search for a fixed time), plus stop and quit for session control.
git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make install
Each tool call takes a command (the UCI command to execute) and an optional session_id (one is generated automatically if omitted). Responses come back as JSON with status (success or error), session_id, the original command, Stockfish's response lines, and an error field when applicable. Sessions spawn Stockfish processes on demand, maintain UCI state across commands within a session, and clean up automatically on completion or timeout, with configurable limits to prevent runaway process spawning.
Configuration is environment-variable driven: server mode (stdio or http, default stdio) with configurable HTTP host/port; Stockfish binary path (default "stockfish"), max concurrent sessions (default 10), session timeout (default 30m), and command timeout (default 30s); and logging level/format/output settings.
When to use - and when NOT to
Use this connector when you want an AI assistant to analyze chess positions or compute best moves using Stockfish's actual engine strength - setting up a position via FEN, running a depth- or time-limited search, and getting back Stockfish's evaluation, rather than relying on the LLM's own (much weaker) chess reasoning.
It requires a Stockfish binary available on the host (or a custom path via MCP_STOCKFISH_PATH) and is scoped to raw UCI protocol interaction - it does not itself provide a chess board UI, move validation beyond what UCI/Stockfish handles, or game-playing orchestration; those need to be built on top of the raw engine responses.
Capabilities
Full UCI command execution against Stockfish: engine initialization and readiness checks, position setup (start position or arbitrary FEN), move search (unconstrained, depth-limited, or time-limited), and search/session control (stop, quit). Concurrent session management with configurable limits and automatic timeout cleanup.
How to install
Clone the repository and run make install. Run in default stdio mode (mcp-stockfish), with a custom Stockfish path (MCP_STOCKFISH_PATH=/your/path mcp-stockfish), or in HTTP mode (MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish). Add to Claude Desktop's mcpServers config with command mcp-stockfish and optional environment variables like MCP_STOCKFISH_LOG_LEVEL.
Who it's for
Chess players, analysts, and developers who want an AI assistant to run real Stockfish position analysis and move search instead of relying on the model's own chess reasoning.
Source README
mcp-stockfish 🐟
A Model Context Protocol server that lets your AI talk to Stockfish. Because apparently we needed to make chess engines even more accessible to our silicon overlords.
🧠⚡🖥️ Your LLM thinks, Stockfish calculates, you pretend you understand the resulting 15-move tactical sequence.
What is this?
This creates a bridge between AI systems and the Stockfish chess engine via the MCP protocol. It handles multiple concurrent sessions because your AI probably wants to analyze seventeen positions simultaneously while you're still figuring out why your knight is hanging.
Built on mark3labs/mcp-go. Because reinventing wheels is for people with too much time.
Features
- 🔄 Concurrent Sessions: Run multiple Stockfish instances without your CPU crying
- ⚡ Full UCI Support: All the commands you need, none of the ones you don't
- 🎯 Actually Works: Unlike your last side project, this one has proper error handling
- 📊 JSON Everything: Because apparently we can't just use plain text anymore
- 🐳 Docker Ready: Containerized for when you inevitably break your local setup
Supported UCI Commands ♟️
| Command | Description |
|---|---|
uci |
Initializes the engine in UCI mode |
isready |
Checks if the engine is ready. Returns readyok |
position startpos |
Sets up the board to the starting position |
position fen [FEN] |
Sets up a position using FEN notation |
go |
Starts the engine to compute the best move |
go depth [n] |
Searches n plies deep. Example: go depth 10 |
go movetime [ms] |
Thinks for a fixed amount of time in milliseconds. Example: go movetime 1000 |
stop |
Stops current search |
quit |
Closes the session |
Quick Start
Installation
git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make install
Usage
# Default mode (stdio, because we're old school)
mcp-stockfish
# With custom Stockfish path (for the special snowflakes)
MCP_STOCKFISH_PATH=/your/special/stockfish mcp-stockfish
# HTTP mode (for the web-scale crowd)
MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish
Configuration ⚙️
Environment Variables
Server Configuration
MCP_STOCKFISH_SERVER_MODE: "stdio" or "http" (default: "stdio")MCP_STOCKFISH_HTTP_HOST: HTTP host (default: "localhost")MCP_STOCKFISH_HTTP_PORT: HTTP port (default: 8080)
Stockfish 🐟 Configuration
MCP_STOCKFISH_PATH: Path to Stockfish binary (default: "stockfish")MCP_STOCKFISH_MAX_SESSIONS: Max concurrent sessions (default: 10)MCP_STOCKFISH_SESSION_TIMEOUT: Session timeout (default: "30m")MCP_STOCKFISH_COMMAND_TIMEOUT: Command timeout (default: "30s")
Logging
MCP_STOCKFISH_LOG_LEVEL: debug, info, warn, error, fatalMCP_STOCKFISH_LOG_FORMAT: json, consoleMCP_STOCKFISH_LOG_OUTPUT: stdout, stderr
Tool Parameters
command: UCI command to executesession_id: Session ID (optional, we'll make one up if you don't)
Response Format
{
"status": "success|error",
"session_id": "some-uuid",
"command": "what you asked for",
"response": ["what stockfish said"],
"error": "what went wrong (if anything)"
}
Session Management
Sessions do what you'd expect:
- Spawn Stockfish processes on demand
- Keep UCI state between commands
- Clean up when you're done (or when they timeout)
- Enforce limits so you don't fork-bomb yourself
Integration
Claude Desktop
{
"mcpServers": {
"chess": {
"command": "mcp-stockfish",
"env": {
"MCP_STOCKFISH_LOG_LEVEL": "info"
}
}
}
}
Development
make deps # Get dependencies
make build # Build the thing
make test # Run tests (when they exist)
make fmt # Make it pretty
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.