chess-uci-mcp

chess-uci-mcp

一个 MCP 桥接程序，为 UCI 国际象棋引擎（如 Stockfish 或 Leela Chess Zero）提供接口。

UCI 端基于 esca 运行：它与引擎通信，并在整个过程中回答桥接程序提出的所有国际象棋问题。

依赖项

你需要安装 Python 3.12 或更高版本，以及 uv/uvx。

用法

要正常运行，需要安装兼容 UCI 的国际象棋引擎，例如 Stockfish（已使用 Stockfish 17 进行测试）。

如果使用 Stockfish，可从 https://stockfishchess.org/download/ 下载。

在 macOS 上，可以使用 brew install stockfish。

你需要找到兼容 UCI 的引擎二进制文件的路径；以下配置示例中的路径为 /usr/local/bin/stockfish（这是在 macOS 上通过 Brew 安装 Stockfish 时的默认路径）。

后续配置应在你的 MCP 设置中完成； 对于 Claude Desktop，该文件为 claude_desktop_config.json（可在设置菜单的开发者中找到，然后选择编辑配置）。

不同操作系统中的完整路径：

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

根据你选择的运行方式，将以下设置添加到 MCP 配置中：

Uvx（推荐）

Uvx 可以直接按名称运行 Python 应用，并在自动创建的虚拟环境中确保安装所有依赖项。 这是运行 chess-uci-mcp 桥接程序的首选方式。

按以下方式设置 MCP 服务配置文件（例如 Claude Desktop 配置文件）：

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

若要向引擎传递选项，请将其添加到 args 数组中。例如，为 Stockfish 设置 Threads 和 Hash 选项：

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

Uv

如果你已在本地克隆仓库并从中运行，请使用此方式：

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

同样，使用 uv 运行时若要传递选项：

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

命令行选项

应用接受以下命令行选项：

• ENGINE_PATH：（必填）兼容 UCI 的国际象棋引擎可执行文件的路径。
• --uci-option 或 -o：设置 UCI 选项。此选项可以多次使用。需要两个参数：选项名称和值（例如 -o Threads 4）。
• --think-time：引擎的默认思考时间，单位为毫秒。默认为 1000。
• --debug：启用调试日志记录。

可用的 MCP 命令

该桥接程序提供以下 MCP 命令：

1. analyze - 分析由 FEN 字符串指定的国际象棋局面
2. get_best_move - 获取某个国际象棋局面的最佳走法
3. set_position - 设置当前国际象棋局面
4. engine_info - 获取国际象棋引擎信息
5. get_engine_options - 获取所有可用 UCI 引擎选项及其元数据和当前值
6. set_engine_options - 在运行时设置一个或多个 UCI 引擎选项

开发

# Clone the repository
git clone https://github.com/AnglerfishChess/chess-uci-mcp.git
# ... or
#    git clone [email protected]: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

发布流程

发布清单位于 .claude/skills/ 下的 releasing 技能中，因此每次发布都按相同流程进行：检查前置条件、更新版本、创建标签、发布 GitHub 版本。发布 GitHub 版本会触发后续流程——.github/workflows/publish.yml 会构建软件包，并通过可信发布者将其上传到 PyPI，随后重新发布 MCP 注册表条目。两者都通过 OIDC 进行身份验证，因此此仓库或任何开发者的机器上都不会存储令牌。

所有步骤都不会自动执行：只有人工发布 GitHub 版本时，才会进行发布。

pyproject.toml 保存版本号，其他所有副本都由它生成：

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

此操作会写入 chess_uci_mcp/__init__.py 和 server.json 中的两个版本字段。传入 --check 则只会报告版本不一致，不会修改任何内容；CI 运行的就是此检查。

MCP 注册表

registry.modelcontextprotocol.io 是公共 MCP 服务的权威索引，Smithery、PulseMCP、Docker Hub 等均会使用它。它没有搜索框；它是一个 API：

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

该服务的列表信息由 server.json 描述，名称为 io.github.AnglerfishChess/chess-uci-mcp。GitHub 身份验证会授予 io.github.<user>/* 命名空间；组织命名空间还要求拥有该组织的 Owner 权限，且名称区分大小写。

PyPI 软件包的所有权通过本 README 顶部附近的 mcp-name: 标记来证明，该标记会成为 PyPI 上的软件包描述。注册表会从已发布的构件中读取此标记，因此仅将它添加到 git 中还不够——只有包含该标记的版本发布到 PyPI 后才算数。另请注意，注册表将 description 限制为 100 个字符，而 PyPI 没有此限制，因此 server.json 使用了单独的一行描述，而非复用项目的描述。

相关项目

• esca — 为此服务提供 UCI 支持的 MIT Rust/Python 国际象棋库。
• chessplaza — 具有各自个性的 AI 国际象棋 hustler，通过此服务进行对弈。

相关网站

经 MCP Review 认证