chess-uci-mcp

An MCP bridge that provides an interface to UCI chess engines (such as Stockfish or Leela Chess Zero).

<!-- mcp-name: io.github.AnglerfishChess/chess-uci-mcp -->

The UCI side runs on esca: it speaks the protocol to the engine and answers every chess question the bridge has along the way.

Dependencies

You need to have Python 3.12 or newer, and also uv/uvx installed.

Usage

To function, it requires an installed UCI-compatible chess engine, like Stockfish (has been tested with Stockfish 17).

In case of Stockfish, you can download it from https://stockfishchess.org/download/.

On macOS, you can use brew install stockfish.

You need to find out the path to your UCI-capable engine binary; for further example configuration, the path is e.g. /usr/local/bin/stockfish (which is default for Stockfish installed on macOS using Brew).

The further configuration should be done in your MCP setup; for Claude Desktop, this is the file claude_desktop_config.json (find it in Settings menu, Developer, then Edit Config).

The full path on different OSes

• macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following settings to your MCP configuration (depending on the way to run it you prefer):

Uvx (recommended)

Uvx is able to directly run the Python application by its name, ensuring all the dependencies, in a automatically-created virtual environment. This is the preferred way to run the chess-uci-mcp bridge.

Set up your MCP server configuration (e.g. Claude Desktop configuration) file as following:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uvx",
    "args": ["chess-uci-mcp@latest", "/usr/local/bin/stockfish"]
  }
}

To pass options to the engine, add them to the args array. For example, to set the Threads and Hash options for Stockfish:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uvx",
    "args": [
      "chess-uci-mcp@latest", 
      "/usr/local/bin/stockfish",
      "-o", "Threads", "4",
      "-o", "Hash", "128"
    ]
  }
}

Uv

Use it if you have the repository cloned locally and run from it:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uv",
    "args": ["run", "chess-uci-mcp", "/usr/local/bin/stockfish"]
  }
}

Similarly, to pass options when running with uv:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uv",
    "args": [
      "run", 
      "chess-uci-mcp", 
      "/usr/local/bin/stockfish",
      "-o", "Threads", "4",
      "-o", "Hash", "128"
    ]
  }
}

Command-line Options

The application accepts the following command-line options:

• ENGINE_PATH: (Required) The path to the UCI-compatible chess engine executable.
• --uci-option or -o: Set a UCI option. This option can be used multiple times. It takes two arguments: the option name and its value (e.g., -o Threads 4).
• --think-time: The default thinking time for the engine in milliseconds. Defaults to 1000.
• --debug: Enable debug logging.

Available MCP Commands

The bridge provides the following MCP commands:

1. analyze - Analyze a chess position specified by FEN string
2. get_best_move - Get the best move for a chess position
3. set_position - Set the current chess position
4. engine_info - Get information about the chess engine
5. get_engine_options - Get all available UCI engine options with their metadata and current values
6. set_engine_options - Set one or more UCI engine options at runtime

Development

# Clone the repository
git clone https://github.com/AnglerfishChess/chess-uci-mcp.git
# ... or
#    git clone git@github.com:AnglerfishChess/chess-uci-mcp.git

cd chess-uci-mcp

# Create a virtual environment
uv venv --python python3.13

# Activate the virtual environment
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows

# Install the package in development mode
#    uv pip install -e .
# or, with development dependencies
uv pip install -e ".[dev]"

# Resync the packages:
uv sync --extra=dev

# Run tests
pytest

# Check code style
ruff check

Release process

The checklist lives in the releasing skill under .claude/skills/, so a release runs the same way every time: preconditions, version bump, tag, GitHub release. Publishing a GitHub release is the trigger — from there .github/workflows/publish.yml builds the package and uploads it to PyPI through a trusted publisher, then republishes the MCP registry entry. Both authenticate over OIDC, so no token is stored in this repository or on any developer's machine.

Nothing is automatic: a release only happens when a human publishes the GitHub release.

pyproject.toml holds the version, and every other copy is derived from it:

uv sync --extra=dev    # updates uv.lock, keeping the dev tools installed
uv run python .claude/skills/releasing/scripts/sync_version.py

That writes chess_uci_mcp/__init__.py and both version fields in server.json. Passing --check instead reports drift without touching anything, which is what CI runs.

The MCP registry

registry.modelcontextprotocol.io is the authoritative index of public MCP servers, consumed by Smithery, PulseMCP, Docker Hub and others. It has no search box; it is an API:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=chess-uci-mcp&limit=3"

The listing is described by server.json, under the name io.github.AnglerfishChess/chess-uci-mcp. GitHub authentication grants the io.github.<user>/* namespace; an organisation namespace additionally requires Owner rights on that organisation, and the name is case-sensitive.

Ownership of the PyPI package is proven by the mcp-name: marker near the top of this README, which becomes the package description on PyPI. The registry reads it from the published artifact, so adding it to git is not enough — it only counts once a release carrying it reaches PyPI. Note also that the registry caps description at 100 characters where PyPI does not, which is why server.json carries its own one-line description rather than reusing the project's.

Related projects

• esca — the MIT Rust/Python chess library that speaks UCI for this server.
• chessplaza — AI chess hustlers with personalities, playing through this server.

Related sites

Certified by MCP Review