{
  "markdown": "# chess-uci-mcp\n\nAn MCP bridge that provides an interface to UCI chess engines (such as Stockfish or Leela Chess Zero).\n\n<!-- mcp-name: io.github.AnglerfishChess/chess-uci-mcp -->\n\nThe UCI side runs on [esca](https://github.com/AnglerfishChess/esca): it speaks the protocol to the engine and\nanswers every chess question the bridge has along the way.\n\n\n## Dependencies\n\nYou need to have Python 3.12 or newer, and also `uv`/`uvx` installed.\n\n## Usage\n\nTo function, it requires an installed UCI-compatible chess engine, like Stockfish (has been tested with Stockfish 17).\n\nIn case of Stockfish, you can download it from https://stockfishchess.org/download/.\n\nOn macOS, you can use `brew install stockfish`.\n\nYou 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).\n\nThe further configuration should be done in your MCP setup;\nfor Claude Desktop, this is the file `claude_desktop_config.json` (find it in **Settings** menu, **Developer**, then **Edit Config**).\n\nThe full path on different OSes\n\n* macOS: `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\n* Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n* Linux: `~/.config/Claude/claude_desktop_config.json`\n\nAdd the following settings to your MCP configuration (depending on the way to run it you prefer):\n\n### Uvx (recommended)\n\nUvx is able to directly run the Python application by its name, ensuring all the dependencies, in a automatically-created virtual environment.\nThis is the preferred way to run the `chess-uci-mcp` bridge. \n\nSet up your MCP server configuration (e.g. Claude Desktop configuration) file as following:\n\n```json\n\"mcpServers\": {\n  \"chess-uci-mcp\": {\n    \"command\": \"uvx\",\n    \"args\": [\"chess-uci-mcp@latest\", \"/usr/local/bin/stockfish\"]\n  }\n}\n```\n\nTo pass options to the engine, add them to the `args` array. For example, to set the `Threads` and `Hash` options for Stockfish:\n\n```json\n\"mcpServers\": {\n  \"chess-uci-mcp\": {\n    \"command\": \"uvx\",\n    \"args\": [\n      \"chess-uci-mcp@latest\", \n      \"/usr/local/bin/stockfish\",\n      \"-o\", \"Threads\", \"4\",\n      \"-o\", \"Hash\", \"128\"\n    ]\n  }\n}\n```\n\n### Uv\n\nUse it if you have the repository cloned locally and run from it:\n\n```json\n\"mcpServers\": {\n  \"chess-uci-mcp\": {\n    \"command\": \"uv\",\n    \"args\": [\"run\", \"chess-uci-mcp\", \"/usr/local/bin/stockfish\"]\n  }\n}\n```\n\nSimilarly, to pass options when running with `uv`:\n\n```json\n\"mcpServers\": {\n  \"chess-uci-mcp\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"run\", \n      \"chess-uci-mcp\", \n      \"/usr/local/bin/stockfish\",\n      \"-o\", \"Threads\", \"4\",\n      \"-o\", \"Hash\", \"128\"\n    ]\n  }\n}\n```\n\n## Command-line Options\n\nThe application accepts the following command-line options:\n\n*   `ENGINE_PATH`: (Required) The path to the UCI-compatible chess engine executable.\n*   `--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`).\n*   `--think-time`: The default thinking time for the engine in milliseconds. Defaults to `1000`.\n*   `--debug`: Enable debug logging.\n\n## Available MCP Commands\n\nThe bridge provides the following MCP commands:\n\n1. `analyze` - Analyze a chess position specified by FEN string\n2. `get_best_move` - Get the best move for a chess position\n3. `set_position` - Set the current chess position\n4. `engine_info` - Get information about the chess engine\n5. `get_engine_options` - Get all available UCI engine options with their metadata and current values\n6. `set_engine_options` - Set one or more UCI engine options at runtime\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/AnglerfishChess/chess-uci-mcp.git\n# ... or\n#    git clone git@github.com:AnglerfishChess/chess-uci-mcp.git\n\ncd chess-uci-mcp\n\n# Create a virtual environment\nuv venv --python python3.13\n\n# Activate the virtual environment\nsource .venv/bin/activate  # On Unix/macOS\n# or\n.venv\\Scripts\\activate     # On Windows\n\n# Install the package in development mode\n#    uv pip install -e .\n# or, with development dependencies\nuv pip install -e \".[dev]\"\n\n# Resync the packages:\nuv sync --extra=dev\n\n# Run tests\npytest\n\n# Check code style\nruff check\n```\n\n### Release process\n\nThe checklist lives in the `releasing` skill under `.claude/skills/`, so a release runs the same way every\ntime: preconditions, version bump, tag, GitHub release. Publishing a GitHub release is the trigger — from there\n`.github/workflows/publish.yml` builds the package and uploads it to PyPI through a\n[trusted publisher](https://docs.pypi.org/trusted-publishers/), then republishes the MCP registry entry. Both\nauthenticate over OIDC, so no token is stored in this repository or on any developer's machine.\n\nNothing is automatic: a release only happens when a human publishes the GitHub release.\n\n`pyproject.toml` holds the version, and every other copy is derived from it:\n\n```bash\nuv sync --extra=dev    # updates uv.lock, keeping the dev tools installed\nuv run python .claude/skills/releasing/scripts/sync_version.py\n```\n\nThat writes `chess_uci_mcp/__init__.py` and both version fields in `server.json`. Passing `--check` instead\nreports drift without touching anything, which is what CI runs.\n\n### The MCP registry\n\n[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) is the authoritative index of public\nMCP servers, consumed by Smithery, PulseMCP, Docker Hub and others. It has no search box; it is an API:\n\n```bash\ncurl -s \"https://registry.modelcontextprotocol.io/v0/servers?search=chess-uci-mcp&limit=3\"\n```\n\nThe listing is described by `server.json`, under the name `io.github.AnglerfishChess/chess-uci-mcp`. GitHub\nauthentication grants the `io.github.<user>/*` namespace; an organisation namespace additionally requires Owner\nrights on that organisation, and the name is case-sensitive.\n\nOwnership of the PyPI package is proven by the `mcp-name:` marker near the top of this README, which becomes the\npackage description on PyPI. The registry reads it from the *published* artifact, so adding it to git is not\nenough — it only counts once a release carrying it reaches PyPI. Note also that the registry caps `description`\nat 100 characters where PyPI does not, which is why `server.json` carries its own one-line description rather\nthan reusing the project's.\n\n## Related projects\n\n* [esca](https://github.com/AnglerfishChess/esca) — the MIT Rust/Python chess library that speaks UCI for this\n  server.\n* [chessplaza](https://github.com/AnglerfishChess/chessplaza) — AI chess hustlers with personalities, playing\n  through this server.\n\n## Related sites\n\n[Certified by MCP Review](https://mcpreview.com/mcp-servers/anglerfishchess/chess-uci-mcp)\n\n",
  "bytes": 6815,
  "sha": "abca164384eb2f45c13be209b9a2d4cba59dcba32b8e5134b2f8d6a6bbb20ea7",
  "repo_slug": "anglerfishchess/chess-uci-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anglerfishchess_chess_uci_mcp_d3024331/readme"
}