Token-efficient MCP server for Ghidra-based reverse engineering. It supports analyzing ELF, Mach-O, and PE binaries and focuses on decompilation and cross-references, with support for Swift, Objective-C, and Hermes. The package is presented as an MCP server and includes PyPI and license badges.
Token-efficient MCP server for Ghidra-based reverse engineering. Analyze ELF, Mach-O, and PE binaries with Swift, Objective-C, and Hermes support β decompile, disassemble, trace calls and value flow, recover data types, and map addresses back to file offsets. Runs on Linux, macOS, and Windows; ships as a Claude Code plugin with a bundled reverse-engineering skill.
Bottom line: a lean, security-first Ghidra MCP. It is read-only by default β analysis tools never mutate your binaries or the server's configuration (which is frozen for the life of the process). The one tool that writes, annotate (rename / comment / prototype), is opt-in (--allow-write) and human-confirmed: every change is approved by you through an MCP elicitation prompt before it's committed, and it fails closed if your client can't ask. You get an analyst-agent that can persist its findings β under supervision β without giving up the read-only safety story.
Quick Start
1. Prerequisites
A 64-bit JDK 21+ and Ghidra 11.x or 12.x are required (tested with Ghidra 12.1.2 and JDK 21).
Ghidra installed via Homebrew (brew install ghidra) or to /opt/ghidra or ~/ghidra is found automatically. Elsewhere β including any Windows install β point GHIDRA_INSTALL_DIR at the extracted ghidra_<version>_PUBLIC folder.
2. Install β pick one
Claude Code plugin (recommended for Claude Code)
MCP server + reverse-engineering skill in one step; prompts for your Ghidra directory. Needs uv on PATH.
pyghidra-lite doctor # Ghidra, JDK, decompiler, project dir, locks; exits 1 on problems
TIP
Plugin users without a shell install can run the same check with uvx pyghidra-lite doctor.
4. Use it
code
You: Analyze the binary at /path/to/binaries/app
Claude: [calls load, info, code...]
Installation
Claude Code plugin
Installs the MCP server (run with uvx, so uv must be on
PATH) together with the pyghidra-lite:reverse-engineering workflow skill, and asks
for your Ghidra directory, cache directory, optional path restriction and whether to
allow annotate:
On Claude Code before 2.1.275, run /plugin marketplace add johnzfitch/pyghidra-lite
first, then /plugin install pyghidra-lite@pyghidra-lite.
The plugin pins an exact package version and runs one server per session. After a
plugin update, run /reload-plugins (or start a new session) to switch to it.
Change the settings later under /config.
WARNING
If you also have a manual pyghidra-lite entry in .mcp.json or ~/.claude.json,
remove it β otherwise every tool appears twice.
PyPI (recommended)
bash
pip install pyghidra-lite
Arch Linux (AUR)
bash
yay -S python-pyghidra-lite
From source
bash
git clone https://github.com/johnzfitch/pyghidra-lite
cd pyghidra-lite
pip install -e .
MCP Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
The HTTP/SSE transports are shared and apply DNS-rebinding protection (Host/Origin
validation). Binding to a non-loopback address additionally requires both
--restrict-path and a bearer token:
bash
pyghidra-lite serve -t streamable-http --host 0.0.0.0 \
--restrict-path /opt/targets \
--auth-token "$PYGHIDRA_LITE_AUTH_TOKEN" \
--allowed-host re.example.com:8000 # if fronted under another hostname
Clients then send Authorization: Bearer <token> on every request. Terminate TLS
at a reverse proxy for remote access.
Tools (9)
pyghidra-lite provides 8 read-only analysis tools plus 1 opt-in write tool, all
auto-detecting format (ELF/Mach-O/PE) and language (Swift/ObjC/Hermes):
π annotate is the only tool that writes. It is disabled unless the server is
started with --allow-write, and every change requires interactive
confirmation (MCP elicitation) before it is committed β clients that can't
confirm get a preview only. See Writing back.
Examples
python
# Import and analyze
load("/path/to/binary", profile="fast")
# Version-track from a prior build, including synthetic IDs for unnamed code
load("/path/to/new.bin", profile="deep", bootstrap="old.bin", bootstrap_mode="all")
# Get overview with full triage
info("mybinary", detail="full")
# List Swift functions
functions("mybinary", type="swift")
# Decompile with CFG
code("mybinary", "main", cfg=True)
# Search strings in background
search("mybinary", ["password", "api_key"], bg=True)
# Get cross-references
xrefs("mybinary", "malloc", depth=2)
# Value flow: SSA p-code, grouped by basic block; each value is defined once
code("mybinary", "parse_header", what="pcode")
# ...or just where one argument's value goes (forward slice; ~10x smaller on real code)
code("mybinary", "parse_header,param_2", what="pcode")
# Raw bytes plus where they live in the file (for patching)
code("mybinary", "0x4011a0,64", what="bytes") # -> hex, ascii, file_offset, block# Recovered struct layouts / enums / typedefs
search("mybinary", "sockaddr", type="types")
Auto-Detection
All tools automatically detect:
Format: ELF, Mach-O, PE
Language: Swift, Objective-C, Hermes/React Native
Runtime: Bun, Node.js, Electron, PyInstaller
Use the type and detail parameters to access format/language-specific features.
Bootstrap Modes
bootstrap_mode="named": transfer only meaningful source names (default).
bootstrap_mode="all": also assign stable synthetic labels to source FUN_* functions during transfer, which is useful for large version-to-version bootstrap workflows where uniqueness matters more than semantics.
Writing back
By default pyghidra-lite is read-only β no tool mutates your binaries. To let
an agent persist findings (rename a function, attach a comment, fix a prototype),
start the server with --allow-write:
bash
pyghidra-lite serve --allow-write # or PYGHIDRA_LITE_ALLOW_WRITE=1
Then the annotate tool becomes usable:
python
annotate("mybinary", target="FUN_00401000", action="rename", name="parse_header")
annotate("mybinary", target="parse_header", action="comment", comment="validates the v2 header")
annotate("mybinary", target="parse_header", action="prototype", prototype="int parse_header(char *buf, int len)")
Every call is human-confirmed: the server sends an MCP elicitation prompt
showing the exact old -> new change, and only commits if you accept. If the
server was started without --allow-write, the tool refuses; if your MCP client
doesn't support elicitation, the tool returns a preview with applied: false
and writes nothing (fail closed). Confirmed changes are written in a single
Ghidra transaction and saved to the on-disk project.
Audit journal. Because MCP elicitation ultimately trusts the client (an
autonomous "auto-approve" client can self-confirm), every write is recorded in
annotate_audit.jsonl next to the projects β and every declined or failed
attempt is logged too. Each line records old -> new, so the journal is both an
accountability trail and an undo log; a flood of entries is your signal that an
auto-agent is churning, and the server also nudges (ctx.warning) as write
volume climbs. The journal is fail-closed and hardened: a write is recorded
before it's applied (if it can't be journaled, it isn't committed), the file
is created 0o600 and opened with O_NOFOLLOW (a symlinked journal is
refused), and it rotates by size so it can't grow without bound.
The server defaults to fast to stay within MCP timeout limits. Use load(fresh=True) to run deeper analysis when needed:
python
# Default import uses fast profile
load("/path/to/binary")
# Re-analyze with deep profile
load("/path/to/binary", profile="deep", fresh=True)
Token Efficiency
pyghidra-lite is designed for minimal token usage:
Compact JSON - results are serialized without indentation, one text block per call
(measured: 33% fewer characters than pretty-printed output across all tools on a sample binary)
No empty fields - false flags, empty tag lists and null context are omitted
Slices, not dumps - code("func,var", what="pcode") returns only the ops a value flows into
(on ws2_32.dllWSAStartup: ~1.9K characters vs ~22K for the full listing)
Opt-in detail - use info(detail="full"), code(cfg=True), or richer type/what modes only when needed
Progress reporting - large imports report progress every 10% or 60s
Truncated strings - long strings capped at 500 chars
Architecture
By default, pyghidra-lite runs as a lightweight stdio proxy (~10MB) that forwards to a persistent shared HTTP backend (~500MB JVM). Multiple sessions share a single JVM instead of each spawning their own.
code
Claude Code session 1 ββstdioββ> proxy βββ
Claude Code session 2 ββstdioββ> proxy βββΌββHTTPββ> shared backend (1 JVM)
Claude Code session 3 ββstdioββ> proxy βββ localhost:19101
The proxy auto-starts the backend on first use, and a file lock plus a port check stop concurrent proxies from spawning duplicates. The backend keeps running until pyghidra-lite stop; binaries idle for 30 minutes are unloaded from memory (the 2 most recent stay loaded) and reload transparently from disk.
IMPORTANT
The proxy reuses whatever backend is already listening, whatever its version. After
upgrading pyghidra-lite, run pyghidra-lite stop so the next session starts the new
code. (serve and the Claude Code plugin run one server per session and don't have
this issue.)
Command
What it does
pyghidra-lite
Stdio proxy (default) -- auto-starts backend
pyghidra-lite serve
Direct stdio server (1 JVM per session)
pyghidra-lite serve -t streamable-http
Start persistent HTTP backend manually
pyghidra-lite stop
Stop the shared backend
pyghidra-lite doctor [--json]
Diagnose the environment (read-only; exit 1 if analysis would fail)
Set PYGHIDRA_LITE_NO_AUTOSTART=1 to disable auto-start (useful with systemd).
Configuration
Every setting is a serve flag or an environment variable (handy in an MCP env block):
Only load binaries under these dirs (env: OS path separator)
PYGHIDRA_LITE_ALLOW_WRITE
--allow-write
off
Enable annotate (still human-confirmed)
PYGHIDRA_LITE_DEFAULT_PROFILE
--profile
fast
Default analysis profile
PYGHIDRA_LITE_TOOL_TIMEOUT
β
300 seconds
Per-call budget so a wedged JVM call can't hang the client; 0 disables
PYGHIDRA_LITE_AUTH_TOKEN
--auth-token
none
Bearer token for HTTP transports (required off-loopback)
PYGHIDRA_LITE_NO_AUTOSTART
β
off
Proxy never spawns a backend
β
--evict-after / --min-loaded
30 min / 2
Memory eviction of idle binaries
β
--autopurge-days
off
Delete projects not opened in N days
Multi-Agent Support
Each binary gets its own Ghidra project, enabling:
Parallel analysis of different binaries
Shared results across agents
Persistent analysis (survives restarts)
Content-addressed storage (same binary = same analysis)
Projects are stored in ~/pyghidra-lite/projects/ (Windows: %LOCALAPPDATA%\pyghidra-lite\projects\),
or in the pre-0.8 location ~/.local/share/pyghidra-lite/projects/ if that already exists.
Override with --project-dir or PYGHIDRA_LITE_PROJECT_DIR. Ghidra 12+ rejects project paths with a
component starting with ., so a legacy ~/.local directory only works with Ghidra 11.x β
pyghidra-lite doctor flags this.