MCP Stockfish

🚀 mcp-stockfish 🐟

A Model Context Protocol server that enables your AI to communicate with Stockfish. 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.

🚀 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

✨ Features

• 🔄 Concurrent Sessions: Run multiple Stockfish instances without overloading your CPU.
• ⚡ Full UCI Support: It provides all the necessary commands without any redundant ones.
• 🎯 Actually Works: Unlike your last side - project, this one has proper error handling.
• 📊 JSON Everything: Apparently, plain text is no longer sufficient.
• 🐳 Docker Ready: Containerized in case you break your local setup.

📚 Documentation

What is this?

This creates a bridge between AI systems and the Stockfish chess engine via the MCP protocol. It can handle multiple concurrent sessions, as your AI might want to analyze seventeen positions simultaneously while you're still trying to figure out why your knight is in a vulnerable position.

Built on [mark3labs/mcp - go](https://github.com/mark3labs/mcp - go). Reinventing the wheel is for those with too much free time.

Supported UCI Commands ♟️

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, fatal
  • MCP_STOCKFISH_LOG_FORMAT: json, console
  • MCP_STOCKFISH_LOG_OUTPUT: stdout, stderr

Tool Parameters

• command: UCI command to execute
• session_id: Session ID (optional, we'll generate one if you don't provide it)

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 function as expected:

• Spawn Stockfish processes on demand.
• Maintain UCI state between commands.
• Clean up when the session ends (or times out).
• Enforce limits to prevent fork - bombing.

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

🔧 Technical Details

The project is built on [mark3labs/mcp - go](https://github.com/mark3labs/mcp - go) to handle the MCP protocol, which creates a bridge between AI systems and the Stockfish chess engine. It can handle multiple concurrent sessions, maintaining UCI state between commands and enforcing limits to prevent system overload.

📄 License

MIT - You can do whatever you want, but don't blame me if it breaks.

Credits 🐟

Powered by Stockfish, a chess engine 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 creating non - substandard chess engines.
• [MCP SDK for Go](https://github.com/mark3labs/mcp - go) for handling the protocol so that I don't have to.
• Coffee