# sonirico/mcp-stockfish [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/sonirico/mcp-stockfish  
**GitHub Stars:** 15  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sonirico-mcp-stockfish

## Description
MCP server connecting AI systems to Stockfish chess engine.

## Tools
Capabilities this server exposes over MCP:

- **command** — UCI command to execute
- **session_id** — Session ID (optional, we'll make one up if you don't)

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-stockfish": {
    "command": "npx",
    "args": ["-y","sonirico-mcp-stockfish"]
  }
}
```

## Documentation

## What sonirico/mcp-stockfish MCP server does

The sonirico/mcp-stockfish MCP server provides an MCP bridge to a locally available Stockfish chess engine. An AI client sends a UCI command through the exposed MCP tool, and the server returns Stockfish's response in a JSON object containing the status, session ID, original command, response lines, and any error details.

The tool accepts two parameters:

- `command`: The UCI command to execute.
- `session_id`: An optional identifier for an existing engine session. If omitted, the server creates one.

The server supports multiple concurrent sessions. Each session starts a Stockfish process when needed, preserves UCI state between commands, and is cleaned up when finished or when its timeout is reached.

## How it works

The server launches Stockfish as a separate process and communicates with it using the Universal Chess Interface. Commands can initialize the engine, check readiness, set a starting position or FEN position, start a search, stop a search, or close a session.

Documented examples include `uci`, `isready`, `position startpos`, `position fen [FEN]`, `go`, `go depth [n]`, `go movetime [ms]`, `stop`, and `quit`. Because the tool accepts a UCI command string, the engine interaction is stateful within each session rather than limited to one isolated request.

The default MCP transport is stdio. An HTTP server mode is also available through configuration, with host and port settings. The implementation uses the Go MCP SDK from `mark3labs/mcp-go`.

## Setup and configuration

The repository's quick-start instructions clone the project, enter its directory, and run `make install`. After installation, start the executable with `mcp-stockfish`. Stockfish must be available as `stockfish` on the executable path unless `MCP_STOCKFISH_PATH` points to a different binary.

The sonirico/mcp-stockfish MCP server uses stdio by default. Set `MCP_STOCKFISH_SERVER_MODE=http` to select HTTP mode. HTTP host and port default to `localhost` and `8080` and can be changed with `MCP_STOCKFISH_HTTP_HOST` and `MCP_STOCKFISH_HTTP_PORT`.

Session behavior can be adjusted with `MCP_STOCKFISH_MAX_SESSIONS`, `MCP_STOCKFISH_SESSION_TIMEOUT`, and `MCP_STOCKFISH_COMMAND_TIMEOUT`. Logging supports configurable level, format, and output destination through the corresponding `MCP_STOCKFISH_LOG_*` variables.

## Tools and capabilities

- Send UCI commands to Stockfish.
- Analyze the standard starting position or a position supplied in FEN notation.
- Request searches by depth or by a fixed time in milliseconds.
- Keep engine state across calls within a session.
- Run several Stockfish sessions concurrently.
- Return structured JSON results and errors.
- Use stdio or configured HTTP server mode.

## Limitations and notes

The server is a bridge around Stockfish; the README does not describe a separate chess notation, board-management, or move-validation API beyond the UCI command tool. Stockfish availability is therefore part of the local setup, and the binary path may need configuration.

The documented default session limit is 10, with a 30-minute session timeout and a 30-second command timeout. These settings may affect long-running or highly concurrent analysis workloads. The README shows Claude Desktop configuration, but does not provide compatibility details for other MCP clients.

The project is licensed under MIT. The sonirico/mcp-stockfish MCP server itself does not list API credentials or external authentication requirements.

_Full upstream README: https://allmcps.com/mcp/sonirico-mcp-stockfish/readme_