Pyghidra Lite

pyghidra-lite

[][pypi] [][pypi] [][pypi] [](LICENSE)

[][ci] [][registry] [][mcp] [](#claude-code-plugin) [][ghidra] [](#quick-start)

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).

# macOS

brew install openjdk@21 brew install ghidra

Ubuntu/Debian

sudo apt install openjdk-21-jdk

Download Ghidra from https://ghidra-sre.org

Arch Linux

sudo pacman -S jdk21-openjdk yay -S ghidra

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_ _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 .

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

Any MCP client Install the package, then add it to your client (Claude Code: .mcp.json in your project or ~/.claude.json ; other clients: see MCP Configuration ).

pip install pyghidra-lite

{

"mcpServers": { "pyghidra-lite": { "command": "pyghidra-lite" } } }

3. Check the environment

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

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:

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

• 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)

pip install pyghidra-lite

Arch Linux (AUR)

yay -S python-pyghidra-lite

From source

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):

{

"mcpServers": { "pyghidra-lite": { "command": "uvx", "args": ["pyghidra-lite"] } } }

uvx auto-installs pyghidra-lite from PyPI on first run. Ghidra is auto-detected; set GHIDRA_INSTALL_DIR in env if needed:

{

"mcpServers": { "pyghidra-lite": { "command": "uvx", "args": ["pyghidra-lite"], "env": { "GHIDRA_INSTALL_DIR": "/path/to/ghidra" } } } }

Claude Code

Create .mcp.json in your project (or ~/.claude.json for global):

{

"mcpServers": { "pyghidra-lite": { "command": "pyghidra-lite" } } }

Direct mode (skip proxy)

For single-session use or debugging, run the server directly:

{

"mcpServers": { "pyghidra-lite": { "command": "pyghidra-lite", "args": ["serve"] } } }

With explicit Ghidra path

{

"mcpServers": { "pyghidra-lite": { "command": "pyghidra-lite", "args": [ "serve", "--ghidra-dir", "/path/to/ghidra" ] } } }

Restrict to specific paths

By default, pyghidra-lite can load binaries from any path (the MCP client handles permissions). Use --restrict-path to lock down access:

{

"mcpServers": { "pyghidra-lite": { "command": "pyghidra-lite", "args": [ "serve", "--restrict-path", "/home/user/binaries", "--restrict-path", "/opt/targets" ] } } }

Shared HTTP transport (network access)

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:

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 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

# 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:

pyghidra-lite serve --allow-write          # or PYGHIDRA_LITE_ALLOW_WRITE=1

Then the annotate tool becomes usable:

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,