pyghidra-lite 0.4.0

Lightweight MCP server for Ghidra-based reverse engineering with iOS, Linux, and game file support

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.

Quick Start

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",
      "args": ["serve", "--allow-path", "/path/to/binaries"]
    }
  }
}

4. Use it

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

Claude: [calls import_binary, list_functions, decompile...]

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", "serve", "--allow-path", "~"]
    }
  }
}

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", "serve", "--allow-path", "~"],
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
      }
    }
  }
}

Claude Code

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

Basic (allow specific paths)

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

With explicit Ghidra path

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

Multiple paths

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

Allow any path (development only)

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

Tools

Core (3)

Tool	Description
import_binary	Import binary with async progress reporting
delete_binary	Remove from project
reanalyze	Re-run with different profile

Discovery (4)

Tool	Description
list_binaries	List loaded binaries
list_functions	Functions with metadata (compact by default)
list_imports	Imports with capability tags
list_exports	Exported symbols

Analysis (8)

Tool	Description
get_function_info	Function metadata and callers/callees
disassemble	Assembly for a function
decompile	Pseudo-C with callees and strings
batch_decompile	Decompile multiple functions
get_xrefs	Cross-references
get_callees	What a function calls
call_graph	Call graph with configurable depth
memory_map	Memory layout with permissions

Search (2)

Tool	Description
search_strings	Strings with xrefs
search_symbols	Symbol name search

Data (2)

Tool	Description
read_bytes	Raw memory
read_string	Null-terminated string

ELF (4)

Tool	Description
elf_info	ELF structure summary
elf_sections	ELF sections
elf_symbols	ELF symbols
elf_got_plt	GOT/PLT entries

Mach-O (3)

Tool	Description
macho_info	Mach-O structure summary
macho_segments	Segments and sections
macho_dylibs	Linked dylibs

Swift (4)

Tool	Description
swift_functions	Swift functions (demangled)
swift_types	Swift types from metadata
swift_decompile	Decompile with demangled names
demangle	Swift symbol demangling

Objective-C (3)

Tool	Description
objc_classes	Objective-C classes
objc_methods	Objective-C methods
objc_decompile	Method decompile

Hermes (3)

Tool	Description
hermes_info	Hermes bundle summary
hermes_components	React component names
hermes_endpoints	API endpoints/URLs

Analysis Profiles

Profile	Use Case
fast	Quick triage, disables 20 slow analyzers (default)
default	Balanced, full Ghidra analysis
deep	Thorough analysis for obfuscated code

The server defaults to fast to stay within MCP timeout limits. Use reanalyze to run deeper analysis when needed:

# Default import uses fast profile
import_binary("/path/to/binary")

# Re-analyze with deep profile when you need more detail
reanalyze("binary-name", profile="deep")

Token Efficiency

pyghidra-lite is designed for minimal token usage:

• Compact output by default - list_functions returns minimal fields
• Opt-in verbosity - pass compact=false for full metadata
• Progress reporting - large imports report progress every 10% or 60s
• Truncated strings - long strings capped at 500 chars

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

Links

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

License

MIT