Kawaiidra MCP

A Ghidra MCP Server for Claude Code - Binary Analysis Made Adorable

Keywords: ghidra mcp ghidra-mcp model-context-protocol binary-analysis reverse-engineering decompiler disassembler claude claude-code

A general-purpose Ghidra MCP server that brings the power of Ghidra's headless analyzer and decompiler to Claude Code and other MCP-compatible AI assistants.

Features

Core Features

• Analyze any binary: PE (Windows), ELF (Linux), Mach-O (macOS), and raw firmware
• Decompile functions: Get C code from compiled binaries
• Disassembly: View assembly listings
• Cross-references: Find function callers and callees
• String analysis: Search and list strings in binaries
• Export results: Save analysis to JSON for further processing
• Multi-project support: Organize analyses into separate Ghidra projects

Advanced Analysis (LLM-Optimized)

• Call graphs: Extract hierarchical function relationships
• Library detection: Identify OpenSSL, zlib, Qt, Windows API, and more
• Semantic search: Find code by behavior (file I/O, network, crypto, memory ops)
• Context extraction: Get functions with all dependencies for complete understanding
• Data structures: Extract struct/class definitions and enums
• Control flow graphs: Analyze function logic with basic blocks
• Vulnerability detection: Pattern-based security analysis with CWE mapping
• Function similarity: Find code reuse based on structural fingerprints
• Smart naming: Suggest better symbol names based on usage patterns

iOS Security Research Tools

• KPP/KTRR detection: Identify kernel patch protection mechanisms
• Mach trap analysis: Analyze syscall tables and trap handlers
• PAC gadget finder: Locate pointer authentication gadgets for ARM64e
• Sandbox analysis: Examine sandbox operations and policy checks
• IOKit class finder: Map IOKit class hierarchies and user clients
• Entitlement checks: Detect entitlement validation code paths
• Kernel symbols: Find and analyze XNU kernel symbols
• Mach port analysis: Analyze IPC and port operations

Android & Mobile Analysis Tools

• Crypto constants: Find AES S-boxes, CRC tables, and crypto magic numbers
• JNI methods: Analyze JNI_OnLoad, Java_* exports, and RegisterNatives calls
• API endpoints: Extract URLs, hostnames, IP addresses, and API paths
• Hardcoded secrets: Find API keys, tokens, passwords, and credentials
• Binary comparison: Diff two binaries to find added/removed/modified functions

GUI Mode & Context Tracking

• Dual-mode support: Works in both headless and GUI-connected modes
• Context tracking: Automatically tracks current address/function from tool operations
• GUI integration: Connect to running Ghidra GUI via ghidra_bridge for real-time selection
• Cursor-aware analysis: Get/set current address and function for workflow continuity

Performance

Kawaiidra supports two execution modes:

The JPype bridge keeps a JVM running in-process, eliminating the ~5-15 second startup overhead of spawning analyzeHeadless for each operation. This is 100-1000x faster for sequential operations.

┌────────────────────────────────────────────────────┐
│  10 function decompilations:                       │
│                                                    │
│  Subprocess mode:  ~2-3 minutes                    │
│  JPype Bridge:     ~0.5 seconds                    │
└────────────────────────────────────────────────────┘

Requirements

• Python 3.10+
• Ghidra 11.0+ (tested with 11.x and 12.0, fully compatible with Ghidra 12.0)
• MCP Python package: pip install mcp

For Maximum Performance (Recommended)

• Java JDK 17+ (for JPype bridge)
• JPype1: pip install JPype1

Quick Start

1. Install Ghidra

Option A: Homebrew (macOS/Linux) - Recommended

# macOS
brew install ghidra

# Linux (Homebrew)
brew install ghidra

Option B: Manual Installation Download Ghidra from ghidra-sre.org and extract it.

2. Install Dependencies

cd kawaiidra-mcp
pip install -r requirements.txt

2b. Enable Fast Mode (Recommended)

For 100-1000x faster operations, install JPype and ensure Java is available:

# Install JPype
pip install JPype1

# Verify Java JDK 17+ is installed
java -version

Installing Java if needed:

# macOS
brew install openjdk@17

# Ubuntu/Debian
sudo apt install openjdk-17-jdk

# Windows (winget)
winget install EclipseAdoptium.Temurin.17.JDK

The bridge auto-enables when both JPype and Java are available. Use the bridge_status tool to verify.

3. Configure Ghidra Path (Optional)

The server auto-detects Ghidra installations in common locations. If auto-detection fails or you want to use a specific version, set GHIDRA_INSTALL_DIR:

Homebrew installations (usually auto-detected):

# macOS (Apple Silicon)
export GHIDRA_INSTALL_DIR=/opt/homebrew

# macOS (Intel)
export GHIDRA_INSTALL_DIR=/usr/local

# Linux
export GHIDRA_INSTALL_DIR=/home/linuxbrew/.linuxbrew

Manual installations:

# Windows
set GHIDRA_INSTALL_DIR=C:\ghidra_11.2_PUBLIC

# Linux/macOS
export GHIDRA_INSTALL_DIR=/opt/ghidra
export GHIDRA_INSTALL_DIR=/Applications/ghidra_11.2_PUBLIC

4. Use with Claude Code

Open the kawaiidra-mcp folder in Claude Code. The MCP server will automatically load from .mcp.json.

Or add to your Claude Code config:

{
  "mcpServers": {
    "kawaiidra": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/kawaiidra-mcp/run_server.py"],
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
      }
    }
  }
}

5. Analyze a Binary

1. Place your binary in the binaries/ folder, or use an absolute path
2. Use the analyze_binary tool to import and analyze
3. Use other tools to explore the analysis

Available Tools

Core Analysis Tools

Advanced Analysis Tools (LLM-Optimized)

iOS Security Research Tools

Android & Mobile Analysis Tools

GUI/Context Tools

Tool Examples

Analyze a Windows Executable

analyze_binary
  file_path: "C:\path\to\target.exe"

Analyze Raw Firmware

analyze_binary
  file_path: "firmware.bin"
  processor: "ARM:LE:32:v7"
  base_address: "0x08000000"

Decompile a Function

get_function_decompile
  binary_name: "target.exe"
  function_name: "main"

Find Functions by Pattern

find_functions
  pattern: "crypt"
  binary_name: "target.exe"

Get Cross-References

get_function_xrefs
  binary_name: "target.exe"
  function_name: "main"
  direction: "from"

Get Call Graph

get_call_graph
  binary_name: "target.exe"
  function_name: "main"
  depth: 3
  direction: "callees"

Detect Libraries

detect_libraries
  binary_name: "target.exe"
  detailed: true

Search for Crypto Code

semantic_code_search
  binary_name: "target.exe"
  pattern: "crypto"

Get Function with Full Context

get_function_with_context
  binary_name: "target.exe"
  function_name: "process_data"
  include_callees: true
  include_data_types: true

Detect Vulnerabilities

detect_vulnerabilities
  binary_name: "target.exe"
  severity: "high"

Get Control Flow Graph

get_control_flow_graph
  binary_name: "target.exe"
  function_name: "main"
  include_instructions: true

Find Similar Functions

find_similar_functions
  binary_name: "target.exe"
  function_name: "encrypt_block"
  threshold: 0.7

Generate Comprehensive Report

generate_report
  binary_name: "target.exe"
  depth: "full"

Depth options: quick (metadata only), standard (+ functions/strings), full (+ decompilation), exhaustive (everything)

Detect Kernel Protections (iOS)

detect_kpp_ktrr
  binary_name: "kernelcache"

Analyze Mach Traps (iOS/macOS)

analyze_mach_traps
  binary_name: "kernelcache"
  include_handlers: true

Find PAC Gadgets (ARM64e)

find_pac_gadgets
  binary_name: "kernelcache"
  gadget_type: "signing"
  max_results: 50

Find IOKit Classes

find_iokit_classes
  binary_name: "IOKit.kext"
  include_vtables: true
  include_user_clients: true

Detect Entitlement Checks

detect_entitlement_checks
  binary_name: "amfid"
  include_context: true

Find Kernel Symbols

find_kernel_symbols
  binary_name: "kernelcache"
  pattern: "proc_"
  symbol_type: "function"

Analyze Mach Ports

analyze_mach_ports
  binary_name: "launchd"
  include_dangerous: true

Find Crypto Constants

find_crypto_constants
  binary_name: "libcrypto.so"
  include_context: true

Analyze JNI Methods

analyze_jni_methods
  binary_name: "libnative.so"
  include_signatures: true

Extract API Endpoints

extract_api_endpoints
  binary_name: "app.so"
  include_params: true

Find Hardcoded Secrets

find_hardcoded_secrets
  binary_name: "libnative.so"
  sensitivity: "high"

Compare Binaries

compare_binaries
  binary_name_a: "app_v1.so"
  binary_name_b: "app_v2.so"
  include_similarity: true

Get Current Address (Context-Aware)

get_current_address

Returns the current address from:

• Ghidra GUI (if GUI mode enabled and connected)
• Context tracker (last decompiled/analyzed address)

Get Current Function

get_current_function

Returns the current function from:

• Ghidra GUI cursor position
• Context tracker (last decompiled function)

Set Current Address (Headless Workflow)

set_current_address
  address: "0x401000"
  binary_name: "target.exe"

Check GUI Status

gui_status

Shows GUI mode configuration, connection status, and context tracker state.

Configuration

Environment Variables

Cache Settings

JPype Bridge Settings (Performance)

GUI Mode Settings

Enabling GUI Mode

GUI mode allows Kawaiidra to connect to a running Ghidra GUI instance, enabling real-time access to cursor position and selection. This is useful for interactive analysis workflows.

Setup Steps:

1. Enable GUI mode:

   # Windows
   set KAWAIIDRA_GUI_MODE=true
   
   # Linux/macOS
   export KAWAIIDRA_GUI_MODE=true
   

2. Install ghidra_bridge (optional dependency):

   pip install ghidra_bridge
   

3. Install the bridge server in Ghidra:

   python -m ghidra_bridge.install_server ~/ghidra_scripts
   

4. Start the bridge server in Ghidra:

   • In Ghidra: Tools > Ghidra Bridge > Run in Background
   • Or run the script manually from Script Manager

5. Verify connection:

   gui_status
   

Note: Even without GUI mode enabled, context tracking works in headless mode. The get_current_address and get_current_function tools automatically track context from your tool operations (e.g., last decompiled function becomes the current function).

Testing

Kawaiidra includes a comprehensive test suite with 166 tests covering all major modules:

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_cache.py -v

Directory Structure

kawaiidra-mcp/
├── .mcp.json           # MCP server configuration
├── README.md           # This file
├── requirements.txt    # Python dependencies
├── run_server.py       # Server entry point
├── src/
│   └── kawaiidra_mcp/
│       ├── server.py   # MCP server implementation
│       ├── config.py   # Configuration management
│       ├── cache.py    # Result caching system
│       ├── bridge/     # JPype bridge for fast execution
│       │   ├── __init__.py
│       │   ├── jpype_bridge.py  # JVM lifecycle & Ghidra API
│       │   └── backend.py       # High-level backend abstraction
│       └── scripts/    # Ghidra headless scripts (fallback)
├── tests/              # Unit test suite (166 tests)
├── projects/           # Ghidra project storage (gitignored)
├── binaries/           # Input binaries (gitignored)
├── exports/            # Exported analysis (gitignored)
└── logs/               # Runtime logs (gitignored)

Supported Binary Formats

Common Processor IDs

For raw binaries, specify the processor manually:

Troubleshooting

"Ghidra not found"

Ensure GHIDRA_INSTALL_DIR points to a valid Ghidra installation with support/analyzeHeadless script.

"MCP SDK not installed"

pip install mcp

Analysis Times Out

Increase timeout with environment variable:

# Windows
set KAWAIIDRA_TIMEOUT=600

# Linux/macOS
export KAWAIIDRA_TIMEOUT=600

Large Binary Memory Issues

Increase JVM memory:

set KAWAIIDRA_MAX_MEMORY=8G

Function Not Found

• Ensure the binary has been analyzed first with analyze_binary
• Try using the function's address instead of name (e.g., 0x401000)
• Check if the function is in a different binary in the project

JPype Bridge Not Starting

Check bridge status:

bridge_status

If bridge shows as unavailable:

1. Install JPype:

   pip install JPype1
   

2. Install Java JDK 17+:

   # macOS
   brew install openjdk@17
   
   # Ubuntu/Debian
   sudo apt install openjdk-17-jdk
   

3. Verify Java is in PATH:

   java -version
   

4. Check JAVA_HOME (if needed):

   export JAVA_HOME=/path/to/jdk
   

The server automatically falls back to subprocess mode if JPype is unavailable.

Bridge Mode Slower Than Expected

• First call per binary takes 2-5s (program loading)
• Subsequent calls should be ~1-50ms
• Use bridge_status to verify bridge is active
• Check KAWAIIDRA_BRIDGE_CACHE_PROGRAMS=true is set

Analysis Reports

Binary analysis reports generated using Kawaiidra MCP can be stored in the md/ folder. See md/README.md for report structure guidelines.

Why "Kawaiidra"?

Because reverse engineering should be fun! This is a cute wrapper around serious tools.

Kawaii (Japanese: cute) + Ghidra = Kawaiidra

License

MIT License

See Also

• Ghidra - NSA's reverse engineering framework
• Model Context Protocol - MCP specification
• Claude Code - AI coding assistant