gdb-multiarch-mcp

An MCP (Model Context Protocol) server that gives AI assistants like Claude direct access to gdb-multiarch for debugging Nintendo Switch executables running on Yuzu or a real console with a GDB stub.

Built on top of Ipiano/gdb-mcp, this fork adds Switch-specific debugging tools for offset-based breakpoints, instruction patching (NOP/stub/replace), frame-pointer backtraces, and address localization — all relative to the game's base address ($main).

What It Does

When Claude (or any MCP client) calls switch_start_session, the server:

1. Launches gdb-multiarch inside WSL
2. Loads the Switch debugging commands (.gdbinit.switch)
3. Connects to the GDB stub via target extended-remote
4. Waits for the application to launch, attaches to it
5. Automatically sets $main to the base address of cross2_Release.nss

From there, all standard GDB operations and Switch-specific tools are available through MCP tool calls.

Prerequisites

• Windows with WSL — gdb-multiarch runs inside WSL (tested with Debian)
• gdb-multiarch installed in WSL (sudo apt install gdb-multiarch)
• Python 3.10+ in WSL
• A GDB stub — either Yuzu's built-in GDB stub or a Switch with sys-gdbstub
• Claude Code (or any MCP-compatible client)

Installation

1. Install gdb-multiarch in WSL

wsl -d Debian
sudo apt install gdb-multiarch

2. Install the MCP server

From Windows, run:

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'

Or from inside WSL:

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

3. Add to 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"

Or manually add to your .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. Verify

claude mcp list

You should see gdb-multiarch: ... - Connected.

Configuration

Set these environment variables in WSL to customize the connection:

To set these, add env to your MCP config:

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

Available Tools

Session Management

Switch Debugging Tools

Standard GDB Tools

All standard gdb-mcp tools are also available:

Troubleshooting

"No route to host" when connecting

WSL networking can be tricky. Try:

1. Confirm SSH is running in WSL: sudo service ssh start
2. Test connectivity: nc -vz <switch_ip> 22225
3. Add a route if needed: sudo ip route add 192.168.1.0/24 via <gateway_ip>
4. Port proxy from Windows PowerShell:

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

GDB stub not responding

• Make sure the game is running on Yuzu/Switch before calling switch_start_session
• Verify Yuzu's GDB stub is enabled in Emulation > Configure > Debug > Enable GDB Stub

Session already running

Call switch_stop_session first, then switch_start_session again.

Credits

• Ipiano/gdb-mcp by Andrew Stelter — the upstream MCP server for GDB that this project is built on
• blujay — the Switch GDB commands (.gdbinit.switch, attach.py, print_addr_setup.py) from smash-ultimate-research-setup. Support blujay on Ko-Fi
• Gdbinit by mammon_, elaine, pusillus, mong, zhang le, l0kit, truthix, fG!, gln — the extended .gdbinit configuration

License

MIT — see LICENSE.