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.

1. Prerequisites

JDK 21+ and Ghidra 11.x are required.

# macOS
brew install openjdk@21
brew install --cask 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 at /opt/ghidra or ~/ghidra is found automatically. Set GHIDRA_INSTALL_DIR only for non-standard paths.

2. Install pyghidra-lite

pip install pyghidra-lite

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

pip install pyghidra-lite

yay -S python-pyghidra-lite

git clone https://github.com/johnzfitch/pyghidra-lite
cd pyghidra-lite
pip install -e .

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

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

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

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

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

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

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"
      ]
    }
  }
}

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.

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.

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

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

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.

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)

pyghidra-lite is designed for minimal token usage:

• 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

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

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 stored in ~/.local/share/pyghidra-lite/projects/.

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

MIT