ChessPal Chess Engine - A Stockfish-powered chess engine exposed as an MCP server using FastMCP

What is ChessPal Chess Engine?

ChessPal Chess Engine is a Stockfish-powered chess engine wrapped as a Model Context Protocol (MCP) server using FastMCP. It calculates best moves and provides chess analysis via MCP tools over SSE (default) or stdio transports. This server is part of the ChessPal project and is intended for developers building MCP-based chess applications or agents.

How to use ChessPal Chess Engine?

Install the package from PyPI with pip install chesspal-mcp-engine, then set the CHESSPAL_ENGINE_PATH environment variable to point to a Stockfish binary (version 17.1 recommended). Start the server using chesspal-mcp-engine (SSE mode) or chesspal-mcp-engine --transport stdio. Connect an MCP client to call tools such as get_best_move_tool, validate_move_tool, get_legal_moves_tool, and get_game_status_tool with a FEN position and optional move history.

Key features of ChessPal Chess Engine

• Robust Stockfish engine integration with proper process management
• Exposes chess functionality via Model Context Protocol (MCP) using FastMCP
• Supports SSE and stdio MCP transports for client interaction
• UCI protocol implementation for chess move generation
• Support for FEN positions and move history
• Flexible engine binary configuration and timeout settings

Use cases of ChessPal Chess Engine

• Integrate a chess engine into an AI agent that can analyze positions and suggest best moves
• Build a chess analysis tool that validates moves and retrieves legal moves via MCP
• Create a chess coaching application that queries the engine for game status and move suggestions
• Enable scripted chess puzzle solvers that communicate over SSE or stdio

FAQ from ChessPal Chess Engine

What are the prerequisites for ChessPal Chess Engine?

Python 3.10 or higher, Poetry for dependency management, and a Stockfish chess engine binary (version 17.1 recommended).

How do I configure the Stockfish binary path?

Set the CHESSPAL_ENGINE_PATH environment variable to point to your Stockfish executable. If unset, the server uses fallback environment variables (CHESSPAL_ENGINE_NAME, CHESSPAL_ENGINE_VERSION, CHESSPAL_ENGINE_OS, CHESSPAL_ENGINE_BINARY) to locate the binary in a predefined engines/ directory structure.

What transports does ChessPal Chess Engine support?

It supports both SSE (Server-Sent Events) over HTTP (default, on 127.0.0.1:9000) and stdio (standard input/output) transports for MCP client communication.

What are the default timeouts?

Engine calculation timeout defaults to 1000ms (configurable via CHESSPAL_ENGINE_TIMEOUT_MS). Response wait timeout is 30s, and SSE client connection timeout is 15s.

How do I request the best move from ChessPal Chess Engine?

Call the get_best_move_tool with a JSON payload containing a "request" wrapper with a "fen" string (required) and an optional "move_history" list. For example: {"request": {"fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", "move_history": []}}.