chess-uci-mcp

chess-uci-mcp

Stockfish や Leela Chess Zero などの UCI チェスエンジンへのインターフェースを提供する MCP ブリッジです。

UCI 側は esca 上で動作し、エンジンとプロトコルで通信して、ブリッジからのあらゆるチェスに関する質問に答えます。

依存関係

Python 3.12 以降と、uv／uvx がインストールされている必要があります。

使い方

動作させるには、Stockfish などの UCI 互換チェスエンジンがインストールされている必要があります（Stockfish 17 でテスト済みです）。

Stockfish の場合は、https://stockfishchess.org/download/ からダウンロードできます。

macOS では、brew install stockfish を使用できます。

UCI 対応エンジンのバイナリへのパスを確認してください。以降の設定例では、パスは /usr/local/bin/stockfish です（Brew を使って macOS にインストールした Stockfish のデフォルトのパスです）。

以降の設定は MCP の設定で行います。 Claude Desktop の場合は、claude_desktop_config.json ファイルです（Settings メニューの Developer から Edit Config を選択して開きます）。

OS ごとのフルパスは次のとおりです。

• 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 - 実行時に 1 つ以上の 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>/* 名前空間が付与されます。組織の名前空間には、その組織のオーナー権限も必要です。また、名前では大文字と小文字が区別されます。

PyPI パッケージの所有権は、この README の上部付近にある mcp-name: マーカーで証明されます。このマーカーは PyPI 上でパッケージの説明になります。レジストリは公開済みの成果物から読み取るため、Git に追加するだけでは不十分です。マーカーを含むリリースが PyPI に公開されて初めて有効になります。また、PyPI では制限されていませんが、レジストリでは description が 100 文字までに制限されます。そのため、server.json にはプロジェクトの説明を再利用せず、独自の 1 行の説明を記載しています。

関連プロジェクト

• esca — このサーバーが UCI で通信する、MIT ライセンスの Rust/Python 製チェスライブラリです。
• chessplaza — このサーバーを通じて対局する、個性を持った AI チェスプレイヤーです。

関連サイト

MCP Review 認定済み