mcp-stockfish

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.

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

Quick Start# Installation

git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make install
```\n\n### Usage
```bash\n\n# Default mode (stdio, because we're old school)
mcp-stockfish\n\n# With custom Stockfish path (for the special snowflakes)
MCP_STOCKFISH_PATH=/your/special/stockfish mcp-stockfish\n\n# HTTP mode (for the web-scale crowd)
MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish
```\n\n## Configuration ⚙️# Environment Variables\n\n#### 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)\n\n#### 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")\n\n#### Logging
- `MCP_STOCKFISH_LOG_LEVEL`: debug, info, warn, error, fatal
- `MCP_STOCKFISH_LOG_FORMAT`: json, console
- `MCP_STOCKFISH_LOG_OUTPUT`: stdout, stderr\n\n## Tool Parameters
- `command`: UCI command to execute
- `session_id`: Session ID (optional, we'll make one up if you don't)\n\n## Response Format
```json
{
  "status": "success|error",
  "session_id": "some-uuid",
  "command": "what you asked for",
  "response": ["what stockfish said"],
  "error": "what went wrong (if anything)"
}
```\n\n## 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\n\n## Integration# Claude Desktop
```json
{
  "mcpServers": {
    "chess": {
      "command": "mcp-stockfish",
      "env": {
        "MCP_STOCKFISH_LOG_LEVEL": "info"
      }
    }
  }
}
```\n\n## Development
```bash
make deps # Get dependencies
make build # Build the thing
make test # Run tests (when they exist)
make fmt # Make it pretty
```\n\n## Credits 🐟
Powered 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. Thanks to:
- The [Stockfish team](https://github.com/official-stockfish/Stockfish) for making chess engines that don't suck
- [MCP SDK for Go](https://github.com/mark3labs/mcp-go) for handling the protocol so I don't have to
- Coffee