gdb-multiarch-mcp

ClaudeのようなAIアシスタントに、YuzuやGDBスタブを備えた実機で動作するNintendo Switchの実行ファイルをデバッグするためのgdb-multiarchへの直接アクセスを提供するMCP（Model Context Protocol）サーバーです。

Ipiano/gdb-mcpをベースに構築されたこのフォークは、オフセットベースのブレークポイント、命令パッチ適用（NOP/スタブ/置換）、フレームポインタによるバックトレース、およびアドレスのローカライズ（すべてゲームのベースアドレス$mainを基準とする）といったSwitch専用のデバッグツールを追加しています。

機能

Claude（または任意のMCPクライアント）がswitch_start_sessionを呼び出すと、サーバーは以下の処理を行います：

1. WSL内でgdb-multiarchを起動

2. Switch用デバッグコマンド（.gdbinit.switch）を読み込み

3. target extended-remote経由でGDBスタブに接続

4. アプリケーションの起動を待機し、アタッチ

5. $mainをcross2_Release.nssのベースアドレスに自動設定

これ以降、すべての標準的なGDB操作およびSwitch専用ツールがMCPツール呼び出しを通じて利用可能になります。

前提条件

• WindowsとWSL — gdb-multiarchはWSL内で実行されます（Debianでテスト済み）

• gdb-multiarch — WSLにインストール済みであること（sudo apt install gdb-multiarch）

• Python 3.10+ — WSL内

• GDBスタブ — Yuzuの内蔵GDBスタブ、またはsys-gdbstubを搭載したSwitch

• Claude Code（またはMCP互換クライアント）

インストール

1. WSLへのgdb-multiarchのインストール

wsl -d Debian
sudo apt install gdb-multiarch

2. MCPサーバーのインストール

Windowsから以下を実行：

wsl.exe -d Debian -e bash -c 'export PATH=$HOME/.local/bin:$PATH && pip install --break-system-packages -e /mnt/c/path/to/gdb-multiarch-mcp'

またはWSL内から：

pip install -e /mnt/c/path/to/gdb-multiarch-mcp

3. Claude Codeへの追加

claude mcp add gdb-multiarch -s user -- wsl.exe -d Debian -e bash -c "export PATH=\$HOME/.local/bin:\$PATH && python3 -m gdb_multiarch_mcp"

または.claude.jsonに手動で追加：

{
  "mcpServers": {
    "gdb-multiarch": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": [
        "-d", "Debian", "-e", "bash", "-c",
        "export PATH=$HOME/.local/bin:$PATH && python3 -m gdb_multiarch_mcp"
      ]
    }
  }
}

4. 確認

claude mcp list

gdb-multiarch: ... - Connectedと表示されるはずです。

設定

接続をカスタマイズするには、WSLで以下の環境変数を設定します：

これらを設定するには、MCP設定にenvを追加します：

{
  "mcpServers": {
    "gdb-multiarch": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": ["..."],
      "env": {
        "SWITCH_IP": "192.168.1.100",
        "SWITCH_PORT": "22225"
      }
    }
  }
}

利用可能なツール

セッション管理

Switchデバッグツール

標準GDBツール

すべての標準的なgdb-mcpツールも利用可能です：

トラブルシューティング

接続時に「No route to host」と表示される

WSLのネットワーク設定は複雑な場合があります。以下を試してください：

1. WSLでSSHが実行されているか確認: sudo service ssh start

2. 接続テスト: nc -vz <switch_ip> 22225

3. 必要に応じてルートを追加: sudo ip route add 192.168.1.0/24 via <gateway_ip>

4. Windows PowerShellからポートプロキシ:

netsh interface portproxy add v4tov4 listenport=22225 listenaddress=127.0.0.1 connectport=22225 connectaddress=<switch_ip>

GDBスタブが応答しない

• switch_start_sessionを呼び出す前に、Yuzu/Switchでゲームが実行されていることを確認してください

• YuzuのGDBスタブがEmulation > Configure > Debug > Enable GDB Stubで有効になっていることを確認してください

セッションが既に実行中

先にswitch_stop_sessionを呼び出し、その後再度switch_start_sessionを呼び出してください。

クレジット

• Ipiano/gdb-mcp (Andrew Stelter) — 本プロジェクトのベースとなっているGDB用アップストリームMCPサーバー

• Coolsonickirby/smash-ultimate-research-setup — 本プロジェクトで使用されている修正版.gdbinit.switchおよびattach.py（自動アタッチスクリプト）

• blujay — オリジナルの.gdbinit.switchコマンド

• GradualSyrup — print_addr_setup.py (アドレスからオフセットへの解決)

• Gdbinit (mammon_, elaine, pusillus, mong, zhang le, l0kit, truthix, fG!, gln) — 拡張.gdbinit設定

ライセンス

MIT — LICENSEを参照してください。