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

A Stockfish-powered chess engine exposed as an MCP server using FastMCP. Calculates best moves via MCP tools accessible over SSE (default) or stdio transports using an MCP client library. Part of the ChessPal project.

Features

- Robust Stockfish engine integration with proper process management
- Exposes engine functionality via the Model Context Protocol (MCP) using FastMCP.
- Supports both SSE and stdio MCP transports for client interaction.
- UCI protocol implementation for chess move generation
- Comprehensive test suite with TDD approach
- Error handling and recovery mechanisms
- Support for FEN positions and move history
- Flexible engine binary configuration

Prerequisites

- Python 3.10 or higher
- Poetry for dependency management (install from Poetry's documentation)
- Stockfish chess engine binary (version 17.1 recommended)

Installation

Install the published package from PyPI using pip:

pip install chesspal-mcp-engine

Installation for development

1. Clone the repository:

git clone https://github.com/wilson-urdaneta/dylangames-mcp-chess-engine.git

cd dylangames-mcp-chess-engine

2. Install dependencies and create virtual environment using Poetry:

poetry install

3. Configure the engine binary:
- Option 1: Set CHESSPAL_ENGINE_PATH environment variable to point to your Stockfish binary
- Option 2: Use the fallback configuration with these environment variables:

     # All variables have defaults, override as needed

     export CHESSPAL_ENGINE_NAME=stockfish     # Default: stockfish

     export CHESSPAL_ENGINE_VERSION=17.1       # Default: 17.1

     export CHESSPAL_ENGINE_OS=macos           # Default: automatically detected based on platform

     export CHESSPAL_ENGINE_BINARY=stockfish   # Default: stockfish (include .exe for Windows)

     

Stockfish Binary Setup

The ChessPal Chess Engine requires a Stockfish binary to run the server and integration tests. You have three options for setting up the binary:

Option 1: Set CHESSPAL_ENGINE_PATH (Recommended)

Point to any Stockfish executable on your system:

```bash