chess-uci-mcp

What is chess-uci-mcp?

An MCP bridge that provides an interface to UCI chess engines (such as Stockfish) for use with MCP-compatible AI clients like Claude Desktop. It is intended for developers or chess enthusiasts who want to integrate chess analysis capabilities into LLM workflows.

How to use chess-uci-mcp?

Requires Python 3.10 or newer, uv/uvx, and a UCI-compatible chess engine binary (e.g., Stockfish). Configure it in your MCP client settings (e.g., claude_desktop_config.json) using either uvx (recommended) or uv commands, specifying the engine path and optional UCI options with -o. Run the server by launching the client; commands are invoked via MCP tools.

Key features of chess-uci-mcp

• Bridges MCP with any UCI-compatible chess engine
• Supports configurable UCI options (e.g., Threads, Hash)
• Provides chess analysis via FEN strings
• Offers best‑move retrieval for a given position
• Allows setting the current board position explicitly
• Reports engine details and supports debug logging

Use cases of chess-uci-mcp

• Let an AI assistant analyze a chess position and return best moves
• Integrate real‑time chess engine evaluation into chat interfaces
• Automate chess puzzle solving or game analysis with LLMs
• Build chess‑teaching tools that connect users to Stockfish via natural language

FAQ from chess-uci-mcp

Which chess engines are supported?

Any engine that implements the UCI protocol. Stockfish (tested with version 17) is recommended; you can install it via brew install stockfish on macOS or download from stockfishchess.org.

How do I pass options like Threads or Hash to the engine?

Use the -o flag followed by the option name and value (e.g., -o Threads 4 -o Hash 128) in the command arguments of your MCP configuration.

What MCP commands does the bridge provide?

It provides analyze (analyze a FEN position), get_best_move, set_position, and engine_info (get engine information).

Can I change the engine's thinking time?

Yes. Use the --think-time command-line option, which sets the default thinking time in milliseconds (default: 1000).

Are there any runtime dependencies besides Python and the engine?

You need uv or uvx installed. The server runs locally and does not require an internet connection or authentication.