mcp-stockfish 🐟

1# mcp-stockfish 🐟
2 
3A 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.
4 
5![Claude Desktop with mcp-stockfish](claude.png)
6 
7> 🧠⚡🖥️ *Your LLM thinks, Stockfish calculates, you pretend you understand the resulting 15-move tactical sequence.*
8 
9## What is this?
10 
11This 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.
12 
13Built on [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go). Because reinventing wheels is for people with too much time.
14 
15## Features
16 
17- **🔄 Concurrent Sessions**: Run multiple Stockfish instances without your CPU crying
18- **⚡ Full UCI Support**: All the commands you need, none of the ones you don't
19- **🎯 Actually Works**: Unlike your last side project, this one has proper error handling
20- **📊 JSON Everything**: Because apparently we can't just use plain text anymore
21- **🐳 Docker Ready**: Containerized for when you inevitably break your local setup
22 
23## Supported UCI Commands ♟️
24 
25| **Command**          | **Description**                                                                |
26| -------------------- | ------------------------------------------------------------------------------ |
27| `uci`                | Initializes the engine in UCI mode                                            |
28| `isready`            | Checks if the engine is ready. Returns `readyok`                              |
29| `position startpos`  | Sets up the board to the starting position                                    |
30| `position fen [FEN]` | Sets up a position using FEN notation                                         |
31| `go`                 | Starts the engine to compute the best move                                    |
32| `go depth [n]`       | Searches `n` plies deep. Example: `go depth 10`                                |
33| `go movetime [ms]`   | Thinks for a fixed amount of time in milliseconds. Example: `go movetime 1000` |
34| `stop`               | Stops current search                                                          |
35| `quit`               | Closes the session                                                            |
36 
37## Quick Start
38 
39### Installation
40 
41```bash
42git clone https://github.com/sonirico/mcp-stockfish
43cd mcp-stockfish
44make install
45```
46 
47### Usage
48 
49```bash
50# Default mode (stdio, because we're old school)
51mcp-stockfish
52 
53# With custom Stockfish path (for the special snowflakes)
54MCP_STOCKFISH_PATH=/your/special/stockfish mcp-stockfish
55 
56# HTTP mode (for the web-scale crowd)
57MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish
58```
59 
60## Configuration ⚙️
61 
62### Environment Variables
63 
64#### Server Configuration
65 
66- `MCP_STOCKFISH_SERVER_MODE`: "stdio" or "http" (default: "stdio")
67- `MCP_STOCKFISH_HTTP_HOST`: HTTP host (default: "localhost") 
68- `MCP_STOCKFISH_HTTP_PORT`: HTTP port (default: 8080)
69 
70#### Stockfish 🐟 Configuration
71 
72- `MCP_STOCKFISH_PATH`: Path to Stockfish binary (default: "stockfish")
73- `MCP_STOCKFISH_MAX_SESSIONS`: Max concurrent sessions (default: 10)
74- `MCP_STOCKFISH_SESSION_TIMEOUT`: Session timeout (default: "30m")
75- `MCP_STOCKFISH_COMMAND_TIMEOUT`: Command timeout (default: "30s")
76 
77#### Logging
78 
79- `MCP_STOCKFISH_LOG_LEVEL`: debug, info, warn, error, fatal
80- `MCP_STOCKFISH_LOG_FORMAT`: json, console  
81- `MCP_STOCKFISH_LOG_OUTPUT`: stdout, stderr
82 
83## Tool Parameters
84 
85- `command`: UCI command to execute
86- `session_id`: Session ID (optional, we'll make one up if you don't)
87 
88## Response Format
89 
90```json
91{
92  "status": "success|error", 
93  "session_id": "some-uuid",
94  "command": "what you asked for",
95  "response": ["what stockfish said"],
96  "error": "what went wrong (if anything)"
97}
98```
99 
100## Session Management
101 
102Sessions do what you'd expect:
103 
104- Spawn Stockfish processes on demand
105- Keep UCI state between commands  
106- Clean up when you're done (or when they timeout)
107- Enforce limits so you don't fork-bomb yourself
108 
109## Integration
110 
111### Claude Desktop
112 
113```json
114{
115  "mcpServers": {
116    "chess": {
117      "command": "mcp-stockfish",
118      "env": {
119        "MCP_STOCKFISH_LOG_LEVEL": "info"
120      }
121    }
122  }
123}
124```
125 
126## Development
127 
128```bash
129make deps     # Get dependencies
130make build    # Build the thing
131make test     # Run tests (when they exist)
132make fmt      # Make it pretty
133```
134 
135## Credits 🐟
136 
137Powered by [Stockfish](https://stockfishchess.org/), the chess engine that's stronger than both of us combined. Created by people who actually understand chess, unlike this wrapper.
138 
139Thanks to:
140 
141- The [Stockfish team](https://github.com/official-stockfish/Stockfish) for making chess engines that don't suck
142- [MCP SDK for Go](https://github.com/mark3labs/mcp-go) for handling the protocol so I don't have to
143- Coffee
144 
145## License
146 
147MIT - Do whatever you want, just don't blame me when it breaks.
148