AI クライアント連携（MCP）

MCP は、AI クライアント（Claude Desktop、Claude Code、Cursor、VS Code の GitHub Copilot、Gemini CLI、Codex CLI など）が外部のツールを呼び出すための共通規格です。ShogiBoardQ の MCP サーバー（shogiboardq-mcp）を登録すると、「この棋譜を CSA に変換して」「この局面を 10 秒解析して」「3手詰を5問作って」のような依頼を AI クライアントに話しかけるだけで、クライアントが ShogiBoardQ の機能を呼び出します。

MCP 仕様の最新版（2026-07-28）と、従来の版（2024-11-05〜2025-11-25）の両方で接続できるため、新旧どちらのクライアントからも使えます。

次のツールは GUI を起動せずに動きます（内部では shogiboardq-cli を実行します）。

render_board_image の出力例：GUI と同じ駒画像・配色で描画され、最後の指し手を強調表示できる。「手番」などの表示と段の表記は ShogiBoardQ の表示言語・棋譜表記の設定に従う

ShogiBoardQ を --automation オプション付きで起動すると、次のツールで画面上の局面や棋譜を読み書きできます。

リソースとして、現在局面の SFEN（shogiboardq://position/current）、現在の棋譜の KIF テキスト（shogiboardq://kifu/current）、登録エンジン（shogiboardq://engines）も提供します。

以下は Linux の例です。/path/to/ShogiBoardQ はリポジトリの場所に置き換えてください。Windows では python3 を python に、パスを C:\\Users\\...\\ShogiBoardQ\\build\\ShogiBoardQ.exe のように書き換えます。設定後はクライアントを再起動（または MCP サーバーを再読み込み）してください。

プロジェクト内で次のコマンドを実行します（--scope user を付けると全プロジェクトで有効）。-- より後ろがサーバーの起動コマンドです。

claude mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

claude mcp list      # 接続状態を確認

「設定」→「開発者」→「構成を編集」で開く claude_desktop_config.json（macOS: ~/Library/Application Support/Claude/、Windows: %APPDATA%\Claude\）に追記します。

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

プロジェクトの .cursor/mcp.json（全プロジェクト共通なら ~/.cursor/mcp.json）に記述します。

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

ワークスペースの .vscode/mcp.json に記述します。VS Code ではトップレベルのキーが servers です。ユーザー全体で使う場合はコマンドパレットの「MCP: Open User Configuration」から同じ形式で追加します。

{
  "servers": {
    "shogiboardq": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

コマンドで登録するか、~/.gemini/settings.json（プロジェクトなら .gemini/settings.json）の mcpServers に記述します。

gemini mcp add -s user \
  -e SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  -e PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  shogiboardq python3 -m shogiboardq_mcp

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

同じホストの Codex クライアントは ~/.codex/config.toml を共有します。コマンドで登録するか、下記の設定を記述してください。python3 は mcp パッケージをインストールした Python を指定します。仮想環境の場合は Python の絶対パスを使ってください。

codex mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

[mcp_servers.shogiboardq]
command = "python3"
args = ["-m", "shogiboardq_mcp"]
startup_timeout_sec = 30
env_vars = ["DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "XDG_CONFIG_HOME"]

[mcp_servers.shogiboardq.env]
SHOGIBOARDQ_EXECUTABLE = "/path/to/ShogiBoardQ/build/ShogiBoardQ"
PYTHONPATH = "/path/to/ShogiBoardQ/mcp"

Linux で GUI を自動起動する場合、コマンドで登録した後も [mcp_servers.shogiboardq] に上記の env_vars を追加してください。ディスプレイ・セッションの環境変数と設定ディレクトリを引き継ぐための指定です。同じテーブルを重複して作らず、既存のテーブルを編集します。

codex mcp get shogiboardq で登録内容を確認し、Codex を再起動して新しい会話を開始してください。CLI では /mcp で接続を確認できます。「ShogiBoardQ の validate_sfen で startpos を検証して」と依頼し、合法手数 30 が返ればツールを実行できています。codex mcp list は登録内容のみを表示します。

画面のない環境でアプリ操作を試す場合は、[mcp_servers.shogiboardq.env] に QT_QPA_PLATFORM = "offscreen" を追加します。この場合、ウィンドウは画面に表示されません。詳細は OpenAI 公式の MCP ドキュメントを参照してください。

自動化 API は既定で無効です。--automation を付けて起動すると、所有者だけがアクセスできるローカルソケットで操作を受け付け、標準出力に automation: listening on ... と表示します。SHOGIBOARDQ_EXECUTABLE を設定しておけば、アプリ操作ツールを最初に呼んだときに MCP サーバーが自動で起動します（起動済みなら接続します）。

./build/ShogiBoardQ --automation
# ソケットの場所を指定する場合
./build/ShogiBoardQ --automation --automation-socket /tmp/shogiboardq.sock

未保存の変更がある状態で棋譜を読み込んだり局面を設定したりする依頼は、discard_unsaved を明示しない限り拒否されます。メニュー動作は許可リスト方式で、終了・上書き保存は実行できません。言語切替は可能で、アプリ再起動後に反映されます。実行できる動作は list_actions で確認できます。

操作するウィンドウやダイアログは、どのツールも target（objectName・selector・タイトルの一部）で指定します。省略するとメインウィンドウです。名前のない部品は get_widget_text / list_dialogs の selector を widget・target に指定して操作できます。ダイアログの再生成・アプリ再起動後は再取得してください。set_widget_value はスライダー・リスト・チェック付きグループ・色にも対応します。メニューは list_menu_actions で階層インデックスを調べ、select_menu_action の path に指定します。

画面を操作するツールは、アプリが操作を実行するまで待ってから返り、対象が隠れた・無効になった・別のダイアログに遮られたなど実行時に操作できなかった場合はエラーを返します。結果の state は、実行済み（done）・操作で開いたモーダルダイアログがまだ開いている（running）・待つ間に実行されなかった（pending）を区別します。ツールが失敗したときのメッセージは、CLI・自動化 API と共通の分類の語（invalid_argument・not_found・file_exists・parse_error など）で始まります。