Ghidra BizHawk MCP

Ghidra BizHawk MCP

A unified MCP (Model Context Protocol) server bridging Ghidra's headless static analysis with BizHawk's live emulation — switch between decompiling a ROM and running it on real hardware in the same session.

GBA ROMs: If analyzing Game Boy Advance ROMs, install pudii/gba-ghidra-loader in your Ghidra installation for proper ROM header parsing, mirrored memory regions, and I/O register maps. The loader repository has pre-built .gpa files for Ghidra 11.x.

Prerequisites

Architecture

┌─────────────────────────────────────────────────────────────────┐│                        MCP Client (Claude / Cursor)              ││  sends JSON-RPC over stdin/stdout                                │└─────────────────────────────┬───────────────────────────────────┘                              │                              ▼┌──────────────────────────────────────────────────────────────────┐│                    ghidra-bizhawk-mcp                            ││  ┌─────────────────────────────────────────────────────────────┐││  │   MCP Server (server.py) — tool registry, stdio dispatch    │││  └──────────────────────────┬──────────────────────────────────┘││                             │                                   ││              ┌──────────────┴──────────────┐                    ││              ▼                              ▼                   ││  ┌────────────────────┐    ┌──────────────────────────────┐    ││  │   GhidraSession    │    │   BizhawkBridge              │    ││  │   pyghidra → JVM   │    │   TCP client → localhost:8766│    ││  │   decompile, etc.  │    └──────────────┬───────────────┘    ││  └────────────────────┘                   │                     │└───────────────────────────────────────────┼─────────────────────┘                                            │ TCP (newline-delimited JSON)                                            ▼                              ┌──────────────────────────────┐                              │   BizHawk (EmuHawk.exe)       │                              │   built-in socket server      │                              │   ┌────────────────────────┐ │                              │   │  bridge.lua            │ │                              │   │  memory read/write     │ │                              │   │  joypad, savestate     │ │                              │   │  frame advance         │ │                              │   └────────────────────────┘ │                              └──────────────────────────────┘

Security Model

The MCP server communicates with the MCP client exclusively over stdin/stdout — no HTTP or network listener. The only local TCP socket is a loopback-only connection (127.0.0.1:8766) between the server and BizHawk's built-in Lua socket server. This is used solely for live-emulation features and is not exposed to the network.

Hardware & Retro Ecosystem Integration

ghidra-bizhawk-mcp includes native out-of-the-box support for retro-reversing automation pipelines via Ghidra's static analysis, plus live emulation via BizHawk's multi-system emulator. The server bundles:

• Nintendo Entertainment System (NES) via GhidraNes
• Super Nintendo Entertainment System (SNES) via native 65816 memory maps
• Game Boy Advance (GBA) via gba-ghidra-loader
• Nintendo DS (NDS) via NTRGhidra
• Nintendo Switch via ghidra-switch-loader
• PlayStation 1 (PSX) via ghidra_psx_ldr
• Sega Genesis / Mega Drive via native 68000 memory maps
• Sega Master System / Game Gear via Ghidra-SegaMasterSystem-Loader
• Sega Dreamcast via native SuperH4 memory maps

Zero-Input Triage — Worked Example (GBA)

The primary entry point is triage_and_load_retro_rom. Call it with any ROM path and the server handles the rest:

# Auto-detect platform, map language, provision sessiontriage_and_load_retro_rom(rom_path="/data/game.gba")# → platform: "Game Boy Advance (GBA)"# → loader:   "GBA ROM Loader"# → arch:     "ARM:LE:32:v4t"
# Decompile the main entry point on the same sessiondecompile_function(address="0x00001c2c")# → decompiled C code for the GBA ROM entry routine
# Search for a known pattern (e.g. 32-bit ARM store-multiple)search_bytes(pattern="09 08 00 01")# → matching addresses labelled "gba_ram_start"

Execution Chaining Flow

Instead of forcing your AI agent to spend cycles manually identifying architecture maps, register layouts, or memory segments, chain the automated ingestion pipeline:

1. Invoke triage_and_load_retro_rom with a target file path.
2. The server headlessly parses the binary file structure (NES\x1a, NTR, NSO0, GBA, SNES title vectors, PS-X EXE, SEGA, TMR SEGA, SEGA ENTERPRISES), binds the matching Ghidra language module (6502:LE:16, ARM:LE:32:v4t, AARCH64:LE:64, 65816:LE:24, MIPS:LE:32, 68000:BE:32, Z80:16, SuperH4:LE:32), loads standard address memory blocks, and links automated signature cache arrays.
3. Use the integrated emulate_slice or emulate_slice_with_taint tools to analyze localized console loops — no physical console hardware or open GDB networking ports needed.

Triage Tool

Quick Start

1. Install

pip install ghidra-bizhawk-mcp

Or from source:

git clone https://github.com/getanirao/ghidra-bizhawk-mcp.gitcd ghidra-bizhawk-mcppip install -e .

2. Set environment

# Required: point to your Ghidra installationexport GHIDRA_INSTALL_DIR=/opt/ghidra_11.2    # Linux / macOSset GHIDRA_INSTALL_DIR=C:\Program Files\ghidra_11.2   # Windows
# Optional: enable live BizHawk emulationexport BIZHAWK_EXE_PATH=/path/to/EmuHawk.exe
# Optional: run in mock mode (no Ghidra/BizHawk needed)export MOCK_MODE=1

3. Run

ghidra-bizhawk-mcp

The server listens on stdin/stdout — pipe it to any MCP-compatible client.

Docker

docker build -t ghidra-bizhawk-mcp .docker run -i --rm -v /path/to/binaries:/data ghidra-bizhawk-mcp

The container bundles JDK 17, Ghidra 11.2, and the server — no host dependencies beyond Docker.

Configuration

Environment Variables

Claude Desktop

Add to your claude_desktop_config.json:

{  "mcpServers": {    "ghidra-bizhawk": {      "command": "ghidra-bizhawk-mcp",      "env": {        "GHIDRA_INSTALL_DIR": "/opt/ghidra_11.2"      }    }  }}

Cursor

Add to your Cursor MCP configuration:

{  "mcpServers": {    "ghidra-bizhawk": {      "command": "ghidra-bizhawk-mcp",      "env": {        "GHIDRA_INSTALL_DIR": "/opt/ghidra_11.2"      }    }  }}

Tools

Session management

Most tools accept an optional session_id parameter — omit it to use the most recently loaded session.

Read / Analysis

Write / Mutation

Assembly-level

Byte-sequence search

Binary diffing

Workspace Sessions

Each analyze_binary call creates a named session. Sessions keep their Ghidra project open independently, so multiple binaries can be loaded concurrently:

# Load two binaries into separate sessionss1 = analyze_binary(binary_path="/bin/a.out")        # auto session_ids2 = analyze_binary(binary_path="/bin/b.out", session_id="my_session")
# Operate on a specific sessiondecompile_function(function_name="main", session_id=s1.session_id)
# Diff themdiff_binaries(session_a=s1.session_id, session_b="my_session")

Deployment

Docker (multi-user / CI)

docker build -t ghidra-bizhawk-mcp .
# Run as an MCP subprocessdocker run -i --rm \  -v /data/binaries:/data \  ghidra-bizhawk-mcp \  --ghidra-dir /opt/ghidra

The Dockerfile bundles Ghidra 11.2 and JDK 17 in a slim Python 3.11 image. Bind-mount your binaries directory at runtime.

MCP Bundle (MCPB — Claude Desktop / Smithery)

Package as a portable .mcpb bundle for one-click install in Claude Desktop or publishing on Smithery.

Prerequisites: Install the MCPB CLI:

npm install -g @anthropic-ai/mcpb

Build the bundle:

# From the repo root — also builds the Smithery publish variantscripts/build-mcpb.ps1

Or manually with mcpb:

mcpb pack

The output ghidra-bizhawk-mcp.mcpb wraps the server with a manifest.json that prompts for GHIDRA_INSTALL_DIR (required) and optionally BIZHAWK_EXE_PATH at install time — no manual JSON editing.

Publishing to Smithery:

Smithery's publish API requires MCP-style tool schemas (inputSchema) and object-form prompt arguments, which the MCPB schema forbids in manifest.json. The build script therefore emits a second bundle whose manifest is patched from mcpb/tool-schemas.json:

python scripts/build_smithery_bundle.pysmithery mcp publish ./dist/ghidra-bizhawk-mcp.smithery.mcpb -n getanirao/ghidra-bizhawk-mcp

P-code micro-emulation

All run inside the pyhidra process via Ghidra's EmulatorHelper — no GDB/LLDB, no network ports, no debugger stubs. Works on ARM, x86, MIPS, and any Ghidra-supported architecture.

Worked example — breaking on a register condition

Suppose you're reversing a GBA ROM and want to find the first time r0 becomes zero inside a loop at 0x08000100:

# Step until r0 == 0, stop before the matching instructionresult = emulate_slice_with_breakpoints(    session_id="gba_v1",    start_address="0x08000100",    max_instructions=5000,    stop_condition="R0==0",    stop_mode="before")# result.exit_reason → "R0==0"# result.instructions_executed → 312# result.trace → [step 311: r0 goes 4→2, step 312: r0 goes 2→0]
# Check if a specific address was reached after a branchresult = emulate_slice_with_breakpoints(    session_id="gba_v1",    start_address="0x08000100",    max_instructions=5000,    stop_condition="PC==0x08001234")# result.exit_reason → "PC==0x08001234"
# Use inequalities to catch bounds checksresult = emulate_slice_with_breakpoints(    session_id="gba_v1",    start_address="0x08000100",    max_instructions=5000,    stop_condition="R1>0xFF")# result.exit_reason → "R1>0xFF"# result.last_step["r1"] → 0x100

This is especially powerful for identifying copy-loop bounds (R3 >= R4), null-pointer paths (R0==0), or switch-table targets (PC==0x).

Function fingerprinting / signature transfer

Persistent signature stash (server-side cache)

Workflow — fully automated persistence:

# Analyze v1 — stashes automatically under binary content hashs1 = analyze_binary(binary_path="/bin/v1.bin")auto_stash_current_binary(session_id=s1.session_id)
# Later, analyze v2 — restores automaticallys2 = analyze_binary(binary_path="/bin/v2.bin")auto_restore_current_binary(session_id=s2.session_id)# → 142 functions renamed, zero manual JSON handling

Try these prompts

After configuring your MCP client (see Configuration), ask your AI agent:

• "Load this GBA ROM and decompile the entry point."
• "What functions call 0x8001234 in this NDS binary?"
• "Triage this PSX EXE and trace r0 through the first 20 instructions."
• "Diff the two sessions I have open and show me changed functions."

Project Structure

ghidra-bizhawk-mcp/├── Dockerfile├── pyproject.toml├── README.md└── src/ghidra_bizhawk_mcp/    ├── __init__.py    ├── server.py          # MCP server, tool registry, stdio transport    ├── ghidra_bridge.py   # GhidraSession — pyghidra wrapper, all Ghidra logic    ├── lua/    │   └── bridge.lua     # BizHawk-side Lua bridge for live emulation    └── tools/        ├── __init__.py        ├── bizhawk_bridge.py  # TCP client connecting MCP ↔ BizHawk        └── ...

How it works

1. pyhidra.start() boots Ghidra's JVM once at server startup
2. Each analyze_binary call opens a new Ghidra project in its own named session
3. Read/write tools route to the requested session via session_id (or the active default)
4. Write tools apply changes directly to the Ghidra program database
5. Sessions persist until explicitly closed — enabling multi-binary workflows and diffing