Ghidra Bundle

A reproducible, self-contained Ghidra 12.2, built from source with eight extensions, Jython, Diablo 2 scripts, PyGhidra with MPQ support and an MCP bridge for AI assistants. Ghidra runs in portable mode: settings, cache and temp files stay in dist/, and ~/.ghidra is never touched. Every built zip is collected in dist/packages/.

Quickstart

git clone --recurse-submodules https://github.com/felipe-dos-santos81/ghidra-bundle.git
cd ghidra-bundle
make install   # install dependencies, build, and test the bundle
make run       # launch Ghidra

make install installs missing prerequisites with sudo apt (Linux) or brew (macOS): JDK 25, Maven, Clang, Python 3.10+, uv, Git, curl, GNU timeout (gtimeout on macOS) and optional StormLib for MPQ support. REA requires npm and Node.js 22.19+, 24.11+ or 26+ on PATH; Node.js is not installed automatically. Run make env to check prerequisites. Java dependencies download on the first build, and completed stages are skipped.

On apt-based Linux distributions, make deps installs openjdk-25-jdk when available. If your distribution does not provide it, install a full JDK 25 yourself and export JAVA25_HOME=/absolute/path/to/jdk before running make deps or make install; no additional package repository is required.

Using the MCP server

A successful make install registers bridge-mcp-ghidra as the ghidra MCP server with opencode (~/.config/opencode/opencode.json) and, if the claude CLI is installed, with Claude Code (user scope).

1. make run, then open a program in the CodeBrowser. This starts the GhidraMCP plugin on 127.0.0.1:8089.
2. make verify confirms the plugin answers.
3. Restart your AI client. In Claude Code, claude mcp get ghidra should report it as connected.

REA

With Node.js available, make install-rea installs REA into .rea/ and registers it as the rea MCP server with the same two clients. REA needs no running Ghidra: it imports one file into a throwaway headless project and returns decompilation, references and strings.

REA 6.3.0 upstream verifies Ghidra 12.1.4 and accepts only 12.1.x. The bundle applies a checked, idempotent patch so exactly Ghidra 12.2 is also compatible, not upstream-verified; 12.2.1 and other versions remain rejected. Java requirements still come from Ghidra's application.properties. The REA sanity section runs policy unit tests, doctor and a real decompilation.

.rea/rea function /path/to/program.exe entry --json   # the same wrapper the MCP server uses

The wrapper .rea/rea points REA at this bundle's Ghidra and JDK; re-run make install-rea after changing Node.js or the JDK. REA's sessions are read-only and deleted on close, and it cannot analyze LE/LX programs, so use the ghidra server for persistent projects and for DOS/4GW or OS/2 programs. Take care with DOS/4GW games: REA does not reject them, it treats them as plain DOS MZ and shows only the 16-bit extender stub. REA adds about 150 tools to each client session.

Make targets

Run make help for the same list.

Testing

make test (also the last stage of make install) builds three tiny programs and checks that Ghidra handles them: an i386 ELF object (core loader and decompiler), a DOS MZ file (GhidraDosToolbox loader and syscall analyzer) and an LE file (lx-loader, including an applied fixup). It then starts GhidraMCP's headless server on port 18089 (TEST_MCP_PORT) and checks it over HTTP. It also checks the JDK 25 runtime, dist/packages/, a headless BinExport export, Jython and the D2 scripts, PyGhidra reading a PKWARE-compressed MPQ, REA policy tests and DOS MZ decompilation (skipped when REA is unavailable), and portable-path isolation. Run a subset with SANITY_ONLY, e.g. SANITY_ONLY=dist,pyghidra make test.

Decompiled output is compared with tests/snapshots/; differences are reported but never fail the run. After a deliberate Ghidra or extension upgrade, review and record the new output with UPDATE_SNAPSHOTS=1 make test.

Windows games

Read a file from an MPQ in a PyGhidra script (run Ghidra with dist/ghidra_12.2_PUBLIC/support/pyghidraRun):

from bundle_mpq import MpqArchive
with MpqArchive("/games/d2/d2data.mpq") as mpq:
    weapons = mpq.read("data/global/excel/weapons.txt")

Storm.dll FLIRT signatures are not included: none are public, and Storm.dll is Blizzard's code.

Layout

ghidra-bundle/
├── Makefile              # Build and install pipeline
├── build-ghidra.sh       # Ghidra source build (called by 02-build-ghidra)
├── scripts/              # Build, toolchain, REA compatibility, and launcher helpers
├── python/bundle-mpq/    # bundle_mpq: ctypes StormLib MPQ reader, installed into PyGhidra's venv
├── ghidra_scripts/       # VerifyExtensions.java, SanityCheck.java (used by make)
├── tests/                # make test: fixtures, probes/, expectations, snapshots, run-sanity.sh
├── ghidra/               # Submodule: NSA Ghidra, tag Ghidra_12.2_build
├── ghidra-mcp/           # Submodule: GhidraMCP
├── lx-loader/            # Submodule: ghidra-lx-loader (fork with the object-permissions fix)
├── dos-toolbox/          # Submodule: GhidraDosToolbox, branch wip-ghidra-12
├── GhidrAssist/          # Submodule: GhidrAssist (fork, branch portable-settings)
├── plugin-ghidra/        # Submodule: RevEng.AI plugin (fork, branch portable-settings)
├── ret-sync/             # Submodule: ret-sync (Ghidra extension in ext_ghidra/)
├── GhidraFindcrypt/      # Submodule: GhidraFindcrypt
├── binexport/            # Submodule: BinExport (Ghidra extension in java/)
├── D2GridraTools/        # Submodule: Diablo 2 scripts (unlicensed; fetched only)
├── .venv/                # Python venv with bridge-mcp-ghidra (git-ignored)
├── .rea/                 # REA's version pin and lockfile; node_modules/ and the rea wrapper are git-ignored
└── dist/                 # Built Ghidra (git-ignored)
    ├── packages/            # Every built zip: Ghidra and each extension
    └── ghidra_12.2_PUBLIC/
        ├── ghidraRun, support/pyghidraRun
        ├── Ghidra/Extensions/   # GhidraMCP/, lx-loader/, dos-toolbox/, GhidrAssist/, plugin-ghidra/,
        │                        # retsync/, GhidraFindcrypt/, BinExport/, Jython/, D2GridraTools/
        └── portable/            # settings/ (incl. PyGhidra's venv), cache/, temp/

Notes

• Changing the Ghidra version: check out the new tag in the ghidra submodule and update GHIDRA_VERSION in the Makefile. Stage 02 refuses to build if they disagree. Upgrades do not migrate projects or settings; remove superseded installations explicitly when no longer needed.
• Ghidra 12.2 compatibility patches: Ghidra 12.2 removed or changed a few extension APIs, so six extensions (GhidraMCP, lx-loader, GhidraDosToolbox, GhidrAssist, RevEng.AI, GhidraFindcrypt) build from fresh copies under dist/build/ where scripts/prepare-extension-source.py applies small, exact compatibility patches; the submodule checkouts stay pristine. ret-sync and BinExport build unmodified.
• Directory names matter: keep extension names from their zips and the GhidrAssist, plugin-ghidra, and GhidraFindcrypt submodule paths. Ghidra requires each jar name to start with its extension directory name; make verify-extensions checks class loading.
• Built zips are collected in dist/packages/, one per artifact; the subprojects' own dist/ folders are emptied of current-version zips.
• Rebuilding: stages skip existing outputs; extensions rebuild when their submodule commit or compatibility patch changes, or when their zip is missing. Run make clean, or delete one extension under dist/.../Ghidra/Extensions/, to rebuild.