ChessPal Stockfish MCP Server Chess Engine

Overview

ChessPal Stockfish MCP Server is a lightweight engine adapter that exposes a Stockfish chess engine over the Model Context Protocol (MCP) using two common transports: HTTP/SSE for network clients and stdio for process-based integrations. It lets you run Stockfish as a microservice so other applications (web UIs, bots, analysis tools) can request best moves, multi-variation analysis, or streaming principal variations without embedding the engine directly.

This server is useful when you want a standard, language-agnostic interface to Stockfish. HTTP/SSE provides easy integration for web apps and remote services (fetch/cURL/EventSource), while stdio lets you spawn the MCP server as a child process from any application and exchange line-delimited JSON messages. The design focuses on predictable I/O, configurable engine options, and minimal operational friction (Docker-friendly, configurable via env or YAML).

Features

• Runs Stockfish as an MCP-compliant engine backend
• Two transport modes:
  • HTTP with JSON request/response
  • SSE (Server-Sent Events) for streaming analysis updates
  • stdio (line-delimited JSON) for process integration
• Configure Stockfish UCI options (threads, hash, multipv, skill level)
• Simple JSON protocol for requests and responses
• Docker-friendly deployment and lightweight server binary
• Suitable for web apps, bots, automated analysis pipelines

Installation / Configuration

Clone the repository and run with Docker (recommended):

git clone https://github.com/wilson-urdaneta/chesspal-mcp-engine.git
cd chesspal-mcp-engine

# Example: run with local Stockfish binary mounted into the container
docker run --rm -p 8080:8080 \
  -v $(pwd)/stockfish:/opt/stockfish \
  -e STOCKFISH_PATH=/opt/stockfish/stockfish \
  -e PORT=8080 \
  wilson-urdaneta/chesspal-mcp-engine:latest

Or build and run locally (assuming a Go or similar toolchain is present in the repo):

# build (if a Go project)
go build -o chesspal-mcp ./cmd/server
./chesspal-mcp --config=config.yaml

Example config.yaml (engine options and server settings):

server:
  host: "0.0.0.0"
  port: 8080
engine:
  path: "/usr/local/bin/stockfish"
  threads: 4
  hash_mb: 64
  multipv: 1
logging:
  level: "info"

Common environment variables (supported by the server):

• STOCKFISH_PATH: path to the Stockfish binary
• PORT: HTTP port (default 8080)
• LOG_LEVEL: log verbosity (info/debug/error)

Adjust Stockfish UCI options (threads, hash, multipv) in the YAML or via env vars depending on your deployment.

Available Resources

• GitHub repository: https://github.com/wilson-urdaneta/chesspal-mcp-engine
• Stockfish official: https://stockfishchess.org
• Example clients: use any HTTP/SSE-capable client (curl, fetch, EventSource) or spawn as a child process for stdio integration

Transport comparison:

Use Cases

1. Web UI: request best move and stream analysis to display improving principal variations.
   • Example HTTP POST (get one-time best move):

curl -X POST "http://localhost:8080/v1/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"stockfish",
    "position":"r1bqkbnr/pppppppp/2n5/8/2B5/5N2/PPPPPPPP/RNBQK2R w KQkq - 2 3",
    "moves":[],
    "limits":{"time_ms":1000,"depth":20}
  }'

2. Live analysis over SSE: stream multi-pv updates as they are computed.
   • Example with curl to keep the event stream open:

curl -N -X POST "http://localhost:8080/v1/stream" \
  -H "Content-Type: application/json" \
  -d '{"model":"stock