# 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... │
└─────────────────────────────────────────────────────────────────────────────┘
```

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

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

```bash
# 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](https://github.com/starsong-consulting/GhydraMCP/releases)
   - In Ghidra: `File → Install Extensions → +` → select the `.zip`
   - Restart Ghidra
   - Enable in `File → Configure → Developer → GhydraMCPPlugin`

2. **Add MCP server:**
   ```bash
   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)

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

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

```python
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`):
```json
{
  "mcpServers": {
    "ghydramcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/GhydraMCP", "ghydramcp"]
    }
  }
}
```

**Claude Code**:
```bash
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](GHIDRA_HTTP_API.md) for full parameter details.

---

## Building from Source

```bash
# 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](https://github.com/LaurieWired/GhidraMCP/), evolved into a comprehensive RE platform.

---

## License

Apache 2.0