pyghidra-lite

Token-efficient MCP server for Ghidra-based reverse engineering. Analyze ELF, Mach-O, and PE binaries with Swift, Objective-C, and Hermes support.

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. Set GHIDRA_INSTALL_DIR only for non-standard paths.

2. Install pyghidra-lite

pip install pyghidra-lite
pyghidra-lite doctor   # checks Ghidra, JDK, decompiler, project dir; exits 1 on problems

3. Add to Claude Code

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

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

4. Use it

You: Analyze the binary at /path/to/binaries/app

Claude: [calls load, info, code...]

Installation

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

# 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")

# 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, 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.

Analysis Profiles

The server defaults to fast to stay within MCP timeout limits. Use load(fresh=True) to run deeper analysis when needed:

# 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
• Compact output by default - functions(binary, type="all") returns minimal {name, addr} pairs
• 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.

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 the backend auto-exits after 30 minutes of idle. A file lock prevents concurrent proxy starts from spawning duplicate backends.

Set PYGHIDRA_LITE_NO_AUTOSTART=1 to disable auto-start (useful with systemd).

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

Links

• PyPI Package
• AUR Package
• MCP Registry
• Issue Tracker
• Contributing
• Security Policy
• Changelog

License

MIT