mcghidra/README.md

GhydraMCP

AI-native reverse engineering. Give Claude (or any MCP client) direct access to Ghidra's analysis engine.

┌─────────────────────────────────────────────────────────────────────────────┐
│  "Analyze the authentication bypass in this firmware"                       │
│                                                                             │
│  Claude: I'll decompile the auth functions and trace the validation logic. │
│                                                                             │
│  [functions_list grep="auth|login|verify"]                                  │
│  [functions_decompile name="verify_password"]                               │
│  [xrefs_list to_addr="0x0040156c"]                                         │
│  [analysis_get_dataflow address="0x00401234" direction="backward"]          │
│                                                                             │
│  Found it. The password check at 0x401580 compares against a hardcoded     │
│  hash, but there's a debug backdoor at 0x401590 that bypasses validation   │
│  when the username starts with "debug_". Let me show you the call graph... │
└─────────────────────────────────────────────────────────────────────────────┘

What You Get

64 MCP tools across 12 categories:

Category	Tools	What it does
Functions	11	Decompile, disassemble, rename, set signatures, list variables
Data	8	Create/modify data items, list strings, set types
Structs	7	Create structs, add/update fields, manage data types
Symbols	9	Create labels, rename symbols, list imports/exports
Analysis	6	Call graphs, data flow, cross-references, run analysis
Memory	2	Read/write raw bytes
Variables	4	List/rename function variables, set types
Bookmarks	3	Create/list/delete analysis bookmarks
Enums/Typedefs	4	Create enum and typedef data types
Namespaces	2	List namespaces and classes
Segments	1	List memory segments with permissions
Docker	7	Auto-start containers, health checks, session management

13 analysis prompts for common RE workflows:

• malware_triage — Quick capability assessment
• identify_crypto — Find crypto functions and constants
• find_authentication — Locate auth, license checks, credentials
• analyze_protocol — Reverse network/file protocols
• trace_data_flow — Taint analysis through functions
• And 8 more specialized prompts...

11 MCP resources for quick enumeration without tool calls.

---

Quick Start

Option 1: Docker (Easiest)

No Ghidra installation needed. Analyze binaries in isolated containers.

# Build the image (once)
cd GhydraMCP && docker build -t ghydramcp:latest -f docker/Dockerfile .

# Add to your MCP config
claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp

Then in Claude:

Analyze /path/to/suspicious.exe

Claude will auto-start a container, wait for analysis, and begin work.

Option 2: Native Ghidra

1. Install the Ghidra plugin:

   • Download latest release
   • In Ghidra: File → Install Extensions → + → select the .zip
   • Restart Ghidra
   • Enable in File → Configure → Developer → GhydraMCPPlugin

2. Add MCP server:

   claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp
   

3. Open a binary in Ghidra, then ask Claude to analyze it.

---

How It Works

┌──────────────┐     MCP      ┌──────────────┐     HTTP     ┌──────────────┐
│    Claude    │◄────────────►│   GhydraMCP  │◄────────────►│    Ghidra    │
│  (or other   │   stdio      │   (Python)   │   REST API   │   Plugin     │
│  MCP client) │              │              │              │   (Java)     │
└──────────────┘              └──────────────┘              └──────────────┘

• Ghidra Plugin: Exposes Ghidra's analysis via HTTP REST API (HATEOAS)
• GhydraMCP Server: Translates MCP tool calls to API requests
• Multi-instance: Analyze multiple binaries simultaneously on different ports
• Session isolation: Docker containers get unique ports, preventing conflicts

---

Usage Patterns

Set Current Instance (Then Forget About Ports)

instances_list()                    # Discover running Ghidra instances
instances_use(port=8192)            # Set as current
functions_list()                    # No port needed!
data_list_strings(grep="password")  # Uses current instance

Docker Workflow

# Start container (returns immediately)
result = docker_auto_start(binary_path="/path/to/malware.exe")
# → {port: 8195, message: "Poll docker_health(port=8195)..."}

# Poll until ready
while True:
    health = docker_health(port=8195)
    if health["healthy"]:
        break
    # Can check docker_logs() while waiting

# Register and use
instances_use(port=8195)
functions_list()  # Ready to analyze

Cursor-Based Pagination

Large binaries can have 100K+ functions. Use cursors:

result = functions_list(page_size=100)
# → {items: [...], cursor_id: "abc123", has_more: true}

# Get next page
cursor_next(cursor_id="abc123")

# Or filter server-side
functions_list(grep="crypto|encrypt", page_size=50)

Analysis Prompts

Built-in prompts for common workflows:

/prompt malware_triage
/prompt identify_crypto
/prompt find_authentication

These guide Claude through systematic analysis with progress reporting.

---

Configuration

Environment Variables

Variable	Default	Description
GHIDRA_HYDRA_HOST	localhost	Ghidra instance host
GHIDRA_HYDRA_PORT	8192	Default port

MCP Config Examples

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ghydramcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/GhydraMCP", "ghydramcp"]
    }
  }
}

Claude Code:

claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp

---

Tool Reference

Instance Management

instances_list          # Discover Ghidra instances (use this first!)
instances_use           # Set current working instance
instances_current       # Show current instance info

Function Analysis

functions_list          # List functions (supports grep, pagination)
functions_get           # Get function details by name or address
functions_decompile     # Decompile to C pseudocode
functions_disassemble   # Get assembly instructions
functions_rename        # Rename a function
functions_set_signature # Set function prototype
functions_set_comment   # Add decompiler comment
functions_create        # Create function at address
functions_variables     # List local variables and parameters

Data Operations

data_list               # List defined data items
data_list_strings       # List strings (with grep filtering)
data_create             # Define data at address
data_rename             # Rename data item
data_set_type           # Change data type
data_delete             # Remove data definition

Cross-References & Analysis

xrefs_list              # Find cross-references to/from address
analysis_get_callgraph  # Generate call graph
analysis_get_dataflow   # Trace data flow forward/backward
analysis_run            # Trigger Ghidra auto-analysis

Structs & Types

structs_list            # List struct definitions
structs_get             # Get struct with all fields
structs_create          # Create new struct
structs_add_field       # Add field to struct
structs_update_field    # Modify existing field
structs_delete          # Remove struct
enums_list / enums_create
typedefs_list / typedefs_create

Docker Management

docker_auto_start       # Start container for binary (auto port allocation)
docker_health           # Check if container API is responding
docker_status           # List all containers and images
docker_start            # Manual container start
docker_stop             # Stop container (session-scoped)
docker_logs             # Get container logs
docker_cleanup          # Remove orphaned containers

See --help or the API docs for full parameter details.

---

Building from Source

# Clone
git clone https://github.com/starsong-consulting/GhydraMCP
cd GhydraMCP

# Build Ghidra plugin
mvn clean package
# → target/GhydraMCP-[version].zip

# Build Docker image
docker build -t ghydramcp:latest -f docker/Dockerfile .

# Run MCP server (for development)
uv run ghydramcp

---

Architecture

GhydraMCP is designed for AI agents:

• Lazy registration: instances_use doesn't block — validates on first real call
• Non-blocking I/O: All Docker/HTTP operations run in thread executors
• Session isolation: Each MCP session gets unique container ports
• Cursor pagination: Handle 100K+ item responses without context overflow
• Server-side grep: Filter results before they hit the wire

Based on GhidraMCP by Laurie Wired, evolved into a comprehensive RE platform.

---

License

Apache 2.0