gdb-multiarch-mcp

一个 MCP（模型上下文协议）服务器，使 Claude 等 AI 助手能够直接访问 gdb-multiarch，以调试在 Yuzu 或带有 GDB 存根的真实主机上运行的任天堂 Switch 可执行文件。

该分支构建于 Ipiano/gdb-mcp 之上，增加了针对 Switch 的调试工具，用于基于偏移量的断点、指令修补（NOP/存根/替换）、帧指针回溯和地址定位——所有这些都相对于游戏的基地址 ($main)。

功能

当 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 工具调用来使用。

先决条件

• 带有 WSL 的 Windows — gdb-multiarch 在 WSL 中运行（已在 Debian 上测试）

• 在 WSL 中安装 gdb-multiarch (sudo apt install gdb-multiarch)

• WSL 中的 Python 3.10+

• 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 中设置这些环境变量以自定义连接：

要设置这些变量，请将 env 添加到你的 MCP 配置中：

{
  "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. 确认 SSH 在 WSL 中运行：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。