ChessPal

You can run ChessPal’s MCP server to access a Stockfish-powered chess engine over MCP using FastMCP. It supports both SSE and stdio transports, letting you interact with the engine to generate moves, validate moves, list legal moves, and check game status from your own tooling or agents.

How to use

Start the MCP server in SSE mode to interact over an HTTP-friendly transport, or use stdio mode for direct tool integrations with your existing tooling. The server exposes tools that let you request the best move for a given FEN, validate moves, enumerate legal moves, and query the current game status. Run your MCP client against the configured host and port (default 127.0.0.1:9000) and call the available tools through the MCP protocol.

To begin, choose one transport:

• SSE (default): Connect to the server and initialize an MCP session, then call the available tools with properly wrapped requests. This is ideal for programmatic clients that communicate over HTTP streams.
• Stdio: Connect through standard input/output for tight integration with local tooling or testing environments.

How to install

Prerequisites you need installed before you start:

• Python 3.10 or higher
• Poetry for dependency management
• Stockfish chess engine binary (version 17.1 recommended)

Install the published package from PyPI using pip:

pip install chesspal-mcp-engine

For development, clone the project and install dependencies with Poetry, then configure the engine binary.

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

Configure the engine binary by setting environment variables. You can either point directly to your Stockfish binary or use the fallback defaults.

# Option 1: point to your Stockfish binary
export CHESSPAL_ENGINE_PATH=/path/to/stockfish

# Option 2: fallback configuration (defaults shown)
export CHESSPAL_ENGINE_NAME=stockfish
export CHESSPAL_ENGINE_VERSION=17.1
export CHESSPAL_ENGINE_OS=macos
export CHESSPAL_ENGINE_BINARY=stockfish

Additional configuration and startup notes

Engine and server configuration is driven through environment variables. The server starts with a default host/port of 127.0.0.1:9000 for MCP connections unless you customize them through your environment.

# Start in SSE mode (default)
poetry run python -m chesspal_mcp_engine.main
# Or explicitly specify SSE transport
poetry run python -m chesspal_mcp_engine.main --transport sse

# Start in Stdio mode
poetry run python -m chesspal_mcp_engine.main --transport stdio

Tools and endpoints you can use

The server provides tools to determine the best move, validate a move, list all legal moves for a position, and check the game status.

Available tools include the following MCP endpoints:

get_best_move_tool
validate_move_tool
get_legal_moves_tool
get_game_status_tool

Notes on usage patterns

When using the SSE client, wrap your requests in the required outer envelope and pass the position in FEN form along with any move history. This ensures the engine can compute the best move accurately.

Troubleshooting and tips

If you cannot connect, verify that the MCP host and port are reachable and that the engine binary is accessible and executable. Ensure the Stockfish binary is properly configured via CHESSPAL_ENGINE_PATH or the fallback environment variables.

For debugging, enable development-level logging and inspect startup messages to confirm the chosen transport and port.

Available tools

get_best_move_tool

Returns the best move for a given chess position, based on the current FEN and move history.

validate_move_tool

Checks whether a provided move is legal in the given position.

get_legal_moves_tool

Lists all legal moves available from the given position.

get_game_status_tool

Provides the current status of the game, such as in progress, check, checkmate, or stalemate.