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

- 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

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

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

The module uses the following environment variables for configuration:

CHESSPAL_ENGINE_PATH=/path/to/your/engine/binary
CHESSPAL_ENGINE_NAME=stockfish       # Default: stockfish

CHESSPAL_ENGINE_VERSION=17.1         # Default: 17.1

CHESSPAL_ENGINE_OS=macos             # Default: auto-detected based on platform

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

MCP_PORT=9000                        # Default: 9000
ENVIRONMENT=development              # Default: development

LOG_LEVEL=INFO                       # Default: INFO for production, DEBUG for development

See .env.example for a complete example configuration.

Command: poetry
Arguments: run python -m chesspal_mcp_engine.main --transport stdio

The project includes both unit tests and integration tests:

poetry run pytest

This runs the complete test suite. Note that integration tests require a Stockfish binary to be available through either Option 1 or 2 above.

poetry run pytest -m "not integration"

This runs only the unit tests, where Stockfish interaction is mocked and no binary is required.

result = await session.call_tool('get_best_move_tool', {
"request": { # Required wrapper field
"fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
"move_history": []
}
})

print(f"Best move: {result.best_move_uci}") # e.g., "e2e4"
```