Ghidra MCP Server

Ghidra MCP Server

A Ghidra headless server exposed via the Model Context Protocol (MCP), designed for binary analysis and malware reverse engineering with AI assistants. Runs locally or in Docker.

Features

• 32 MCP tools for binary analysis: decompilation, function listing, string search, cross-references, byte pattern search, malware-focused analysis, advanced RE tools (CFG, call graphs, instruction search), and emulation
• 3 emulation tools — emulate functions with automatic calling convention handling, single-step through code, read registers and memory
• 5 MCP resources for browsing binary metadata, functions, strings, and imports
• Multi-binary support — analyze multiple binaries simultaneously in a single Ghidra project
• Malware analysis tools — entropy analysis (packing detection), suspicious API categorization, section anomaly detection
• Code Mode — token-saving operating mode that exposes only 2 tools (search + execute) instead of all 32, for LLM-efficient usage
• Ghidra Server — connect to a shared Ghidra server for collaborative reverse engineering with checkout/checkin workflow
• SSE transport — run as an HTTP server with --transport sse for network-accessible deployments
• Docker or local — runs in an isolated container or directly on your machine via stdio transport
• PyGhidra 3.0 — direct Ghidra Java API access via in-process JVM (no Ghidra scripts needed)

Quick Start

Docker (recommended)

# Build the image
docker compose build

# Run in full mode (all 32 tools)
docker compose run --rm -i ghidra-mcp

# Run in code mode (2 tools: search + execute, saves tokens)
docker compose run --rm -i ghidra-mcp --mode code

See Client Configuration for setup with Claude Desktop, Claude Code, OpenCode, and Continue.dev.

Apple Silicon

The Docker image builds natively on arm64. Since Ghidra releases don't include pre-built linux_arm_64 decompiler binaries, the Dockerfile automatically builds the decompiler from source during docker compose build (adds ~2 min to build time, requires no extra configuration). If you encounter issues, you can force x86_64 emulation by uncommenting platform: linux/amd64 in docker-compose.yml (slower due to Rosetta/QEMU).

Local (no Docker)

Prerequisites

• Python 3.11+ — python.org/downloads. On Windows, check "Add Python to PATH" during installation.
• Java 21+ (e.g., OpenJDK 21) — JAVA_HOME must be set and java must be on your PATH.
• Linux/macOS: export JAVA_HOME=/path/to/jdk-21 (add to ~/.bashrc or ~/.zshrc)
• Windows: Set JAVA_HOME via System Properties > Environment Variables (e.g., C:\Program Files\Eclipse Adoptium\jdk-21)
• Ghidra 12.0.4 — download and extract (no installer needed).
• GHIDRA_INSTALL_DIR environment variable pointing to your Ghidra installation.
• Linux/macOS: export GHIDRA_INSTALL_DIR=/path/to/ghidra_12.0.4_PUBLIC (add to ~/.bashrc or ~/.zshrc)
• Windows: Set via System Properties > Environment Variables, or set GHIDRA_INSTALL_DIR=C:\ghidra\ghidra_12.0.4_PUBLIC in Command Prompt

Installation

Quick install (checks prerequisites, creates venv, installs):

# Linux/macOS
./scripts/install.sh

# Windows (PowerShell)
.\scripts\install.ps1

Manual install:

python -m venv venv

# Linux/macOS:
source venv/bin/activate

# Windows (Command Prompt):
venv\Scripts\activate

# Windows (PowerShell):
venv\Scripts\Activate.ps1

pip install -e .

Usage

# Activate the virtual environment first (see Installation for Windows commands)
source venv/bin/activate

# Full mode (default) — all 32 tools
ghidra-mcp

# Code mode — 2 meta-tools (search + execute)
ghidra-mcp --mode code

# Custom project directory and name
ghidra-mcp --project-dir ~/my-projects --project-name my_project
# Windows: ghidra-mcp --project-dir C:\Users\you\my-projects --project-name my_project

# SSE transport (HTTP server on localhost:8080)
pip install -e ".[sse]"
ghidra-mcp --transport sse

# SSE with custom host and port
ghidra-mcp --transport sse --host 0.0.0.0 --port 3000

See Client Configuration for setup with Claude Desktop, Claude Code, OpenCode, and Continue.dev.

Client Configuration

All examples show full mode. For code mode, append --mode code (Docker: add "--mode", "code" to the args array; Local: add "--mode", "code" to args or the command).

Claude Desktop

Config file: claude_desktop_config.json

Docker:

{
  "mcpServers": {
    "ghidra": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
    }
  }
}

Local:

{
  "mcpServers": {
    "ghidra": {
      "command": "/path/to/venv/bin/ghidra-mcp",
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
      }
    }
  }
}

Note: Use the full path to ghidra-mcp inside your virtual environment. If GHIDRA_INSTALL_DIR is already set in your shell profile, you can omit the env block. Windows: Use C:\path\to\venv\Scripts\ghidra-mcp.exe as the command and Windows-style paths for GHIDRA_INSTALL_DIR.

Claude Code

Docker — via CLI:

claude mcp add ghidra -- docker compose -f /path/to/docker-compose.yml run --rm -i ghidra-mcp

Docker — via project config (.mcp.json in project root):

{
  "mcpServers": {
    "ghidra": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
    }
  }
}

Local — via CLI:

claude mcp add ghidra --env GHIDRA_INSTALL_DIR=/path/to/ghidra_12.0.4_PUBLIC -- /path/to/venv/bin/ghidra-mcp

Local — via project config (.mcp.json):

{
  "mcpServers": {
    "ghidra": {
      "command": "/path/to/venv/bin/ghidra-mcp",
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
      }
    }
  }
}

Note: Use the full path to ghidra-mcp inside your virtual environment. If GHIDRA_INSTALL_DIR is already set in your shell profile, you can omit the env block and --env flag. Windows: Use C:\path\to\venv\Scripts\ghidra-mcp.exe as the command and Windows-style paths for GHIDRA_INSTALL_DIR.

OpenCode

Config file: opencode.json (project root or ~/.config/opencode/opencode.json)

Docker:

{
  "mcp": {
    "ghidra": {
      "type": "local",
      "command": ["docker", "compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"],
      "enabled": true
    }
  }
}

Local:

{
  "mcp": {
    "ghidra": {
      "type": "local",
      "command": ["/path/to/venv/bin/ghidra-mcp"],
      "environment": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
      },
      "enabled": true
    }
  }
}

Note: Use the full path to ghidra-mcp inside your virtual environment. If GHIDRA_INSTALL_DIR is already set in your shell profile, you can omit the "environment" block. Windows: Use C:\path\to\venv\Scripts\ghidra-mcp.exe in the command array and Windows-style paths for GHIDRA_INSTALL_DIR.

Continue.dev

Config file: .continue/mcpServers/ghidra.json

Note: MCP tools are only available in Continue's Agent mode, not Chat mode.

Docker:

{
  "mcpServers": [
    {
      "name": "Ghidra",
      "type": "stdio",
      "command": "docker",
      "args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
    }
  ]
}

Local:

{
  "mcpServers": [
    {
      "name": "Ghidra",
      "type": "stdio",
      "command": "/path/to/venv/bin/ghidra-mcp",
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
      }
    }
  ]
}

Note: Use the full path to ghidra-mcp inside your virtual environment. If GHIDRA_INSTALL_DIR is already set in your shell profile, you can omit the env block. Windows: Use C:\path\to\venv\Scripts\ghidra-mcp.exe as the command and Windows-style paths for GHIDRA_INSTALL_DIR.

Server Modes

The server supports three operating modes, selectable via the --mode flag:

| Mode | Flag | Tools Registered | Use Case | |------|------|-----------------|----------| | Full | --mode full (default) | All 32 tools + 5 resources | Direct tool access, best for exploration and interactive use | | Code | --mode code | 2 tools (search + execute) | Token-efficient, best for automated pipelines and cost-sensitive usage | | Script | --mode script | 6 tools (search_api + get_class_info + execute_script + binary management) | Direct Ghidra Java API access via live reflection and Python code execution |

Full and Code modes provide identical analytical capabilities — Code Mode routes calls through a dynamic dispatcher instead of registering each tool individually. Script Mode goes further by exposing the raw Ghidra Java API for custom analysis not covered by the built-in tools.

MCP Tools (Full Mode)

Project Management

| Tool | Description | |------|-------------| | import_binary | Import a binary file for analysis | | upload_binary | Upload a binary via base64-encoded data | | list_binaries | List all imported binaries | | delete_binary | Remove a binary from the project |

Analysis

| Tool | Description | |------|-------------| | list_functions | List functions with pagination and name filtering | | decompile_function | Decompile a function to C pseudocode | | rename_function | Rename a function | | rename_variable | Rename a variable (parameter or local) within a function | | rename_label | Rename a symbol/label in the program | | list_strings | List defined strings | | search_strings | Search strings by substring or regex | | list_imports | List imported symbols | | list_exports | List exported symbols | | get_xrefs | Get cross-references to/from an address | | search_bytes | Search for hex byte patterns with wildcards | | get_memory_bytes | Read raw bytes from an address | | search_instructions | Regex search over disassembly mnemonics/operands |

Malware Analysis

| Tool | Description | |------|-------------| | get_entropy | Per-section Shannon entropy, packing detection | | detect_suspicious_apis | Categorized suspicious imports (injection, persistence, crypto, network, anti-debug) | | get_sections | Sections with permissions, entropy, and anomaly flags (W+X, unusual names) |

Advanced Analysis

| Tool | Description | |------|-------------| | get_function_summary | Rich function metadata (params, callees, callers, strings, complexity) without decompilation | | get_basic_blocks | Control-flow graph basic blocks with instructions and edges | | get_call_graph | Function call graph with BFS depth control (callees/callers/both) |

Emulation

Emulate functions using Ghidra's EmulatorHelper API. The emulator automatically handles calling conventions — arguments are placed in the correct registers or stack locations based on the function's parameter metadata, and return values are extracted from the appropriate return register.

| Tool | Description | |------|-------------| | emulate_function | Emulate a function with optional integer arguments, get return value | | emulate_step | Single-step an existing emulator session, read registers and memory | | emulate_session_destroy | Destroy an emulator session and free its resources |

Server Connectivity

Connect to a shared Ghidra server for collaborative reverse engineering. Programs opened from the server are available to all analysis tools. Supports checkout/checkin workflow with exclusive locking.

| Tool | Description | |------|-------------| | connect_server | Connect to a Ghidra server (host, port, username, optional password) | | disconnect_server | Disconnect from server, release checkouts, clean up | | list_repositories | List available repositories on the connected server | | list_server_files | List files and subfolders in a server repository | | open_from_server | Open a program from the server for analysis (with optional checkout) | | checkin_file | Check in changes back to the Ghidra server |

Server Workflow

# 1. Connect to the Ghidra server
connect_server(host="ghidra.example.com", port=13100, username="analyst")

# 2. Browse available repositories and files
list_repositories()
list_server_files(repository_name="malware-lab")

# 3. Open a program (checkout for editing)
open_from_server(repository_name="malware-lab", file_path="/samples/trojan.exe", checkout=True)

# 4. Analyze with any tool — decompile, rename functions, etc.
decompile_function(binary_name="trojan.exe", name_or_addr="main")
rename_function(binary_name="trojan.exe", old_name="FUN_00401000", new_name="decrypt_payload")

# 5. Save changes back to the server
checkin_file(binary_name="trojan.exe", comment="Identified decryption routine")

# 6. Disconnect when done
disconnect_server()

Emulation Workflow

The typical emulation workflow is:

1. Start emulation with emulate_function — sets up the emulator, places arguments, runs until the function returns or the step limit is reached, and returns the result including the return value.

1. Inspect interactively (optional) with emulate_step — after emulate_function creates a session, you can single-step through the remaining execution, reading specific registers and memory regions at each step.

1. Clean up with emulate_session_destroy — disposes the emulator and frees resources. Sessions are also cleaned up automatically when a binary is deleted or the server shuts down.

Emulation Example

# Step 1: Emulate a function with arguments
emulate_function(binary_name="malware.exe", name_or_addr="decrypt_string", args=[0x00402000, 16])
# Returns: {
#   "session_key": "malware.exe:decrypt_string",
#   "return_value": 4198400,
#   "steps_executed": 847,
#   "hit_breakpoint": true,
#   ...
# }

# Step 2: Inspect registers and memory after execution
emulate_step(binary_name="malware.exe", name_or_addr="decrypt_string",
             count=0, read_registers=["RAX", "RCX"],
             read_memory=[{"address": "0x00402000", "size": 32}])
# Returns: {
#   "registers": {"RAX": "0x401000", "RCX": "0x0"},
#   "memory": [{"address": "0x00402000", "hex": "48656c6c6f..."}],
#   ...
# }

# Step 3: Clean up
emulate_session_destroy(binary_name="malware.exe", name_or_addr="decrypt_string")

Emulation Limitations

• External calls: If the emulated function calls imported/external functions (e.g., printf, malloc), emulation will stop or produce undefined behavior. Only self-contained functions emulate correctly without additional stubbing.
• Architecture support: x86/x86-64 (push sentinel return address to stack) and ARM/AARCH64 (set LR register) are supported. Other architectures will raise an error.
• Integer arguments only: The current implementation handles integer arguments via register/stack writes. Floating-point and struct arguments are not supported.
• Step limit: A max_steps parameter (default: 10,000) prevents runaway emulation.

MCP Resources

| URI | Description | |-----|-------------| | ghidra://binaries | All binaries in the project | | ghidra://binary/{name}/info | Binary metadata (arch, format, hashes, entry point) | | ghidra://binary/{name}/functions | Full function list | | ghidra://binary/{name}/strings | All defined strings | | ghidra://binary/{name}/imports | All imported symbols |

Code Mode

Code Mode is a token-efficient operating mode that replaces all 32 individual tool registrations with just 2 meta-tools: search and execute. This dramatically reduces the number of tool schemas sent to the LLM on every request, saving tokens and cost while preserving full analytical capability.

Activation

# Docker
docker compose run --rm -i ghidra-mcp --mode code

# Local
ghidra-mcp --mode code

Tools

search(query?)

Search the tool catalog. Returns tool names, descriptions, and full parameter signatures.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Substring to filter tool names and descriptions. Returns all 32 tools if omitted. |

Example — find emulation tools: ``` search(query="emulate")

Returns:

[

{"tool": "emulate_function", "description": "Emulate a function with optional arguments...",

"parameters": [{"name": "binary_name", "type": "string", "required": true}, ...]},

{"tool": "emulate_step", ...},

{"tool": "emulate_session_destroy", ...}

]

**Example — find tools related to entropy:**

search(query="entropy")

Returns tools whose name or description contains "entropy"

#### `execute(method, params?)`

Execute any Ghidra analysis tool by name with the given parameters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `method` | string | Yes | Tool name from the catalog (use `search` to discover available tools). |
| `params` | object | No | Keyword arguments as a dictionary. Omit for tools with no required params. |

**Example — list functions:**

execute(method="list_functions", params={"binary_name": "test.elf", "filter": "main", "limit": 10}) ```

Example — decompile a function: `` execute(method="decompile_function", params={"binary_name": "test.elf", "name_or_addr": "main"}) ``

Example — emulate a function: `` execute(method="emulate_function", params={"binary_name": "test.elf", "name_or_addr": "decrypt", "args": [1, 2]}) ``

Example — list all binaries (no params needed): `` execute(method="list_binaries") ``

Error Handling

• Unknown method: Raises ValueError with the list of all available method names.
• Missing required parameter: Raises TypeError from the underlying Python method call.
• Bridge errors: KeyError (binary not found), RuntimeError (decompilation failure), etc. propagate directly with descriptive messages.

When to Use Code Mode

| Scenario | Recommended Mode | |----------|-----------------| | Interactive exploration with Claude Desktop | Full | | Automated analysis pipelines | Code | | Cost-sensitive / high-volume usage | Code | | First time using the server | Full | | LLM with small context window | Code | | Custom analysis beyond built-in tools | Script | | Exploring Ghidra API for scripting | Script |

Script Mode

Script Mode provides direct access to the Ghidra Java API via live reflection and Python code execution. Instead of using pre-built tools, the LLM can search API classes, inspect method signatures, and execute arbitrary Python code with full Ghidra API access — like a programmable Ghidra scripting environment.

Activation

# Docker
docker compose run --rm -i ghidra-mcp --mode script

# Local
ghidra-mcp --mode script

Tools

search_api(query, package?)

Search Ghidra Java API classes and methods by keyword using live Java reflection.

search_api(query="FunctionManager")
# Returns class info with all method signatures

search_api(query="getParameters", package="ghidra.program.model.listing")
# Returns classes in that package with matching methods

get_class_info(class_name)

Get full reflection info for a specific class — methods, parameter types, return types, interfaces.

get_class_info(class_name="ghidra.program.model.listing.Function")
# Returns: {"class": "...", "methods": [{"name": "getName", "params": [], "returns": "String"}, ...]}

get_class_info(class_name="Function")  # Short name also works

execute_script(code, binary_name?)

Execute a Python code snippet with full Ghidra Java API access.

execute_script(
    binary_name="malware.exe",
    code="""
fm = program.getFunctionManager()
funcs = list(fm.getFunctions(True))
result = []
for f in funcs[:5]:
    result.append({
        'name': f.getName(),
        'addr': str(f.getEntryPoint()),
        'cc': f.getCallingConventionName(),
    })
return result
"""
)

Pre-defined variables in script scope:

• bridge — GhidraBridge instance
• program / currentProgram — Program object (if binary_name provided)
• monitor — ConsoleTaskMonitor
• All ghidra.* packages importable via normal Python imports

Configuration

CLI Flags

| Flag | Default | Description | |------|---------|-------------| | --mode | full | Server mode: full, code, or script | | --transport | stdio | Transport protocol: stdio or sse | | --host | localhost | Host to bind for SSE transport | | --port | 8080 | Port to bind for SSE transport | | --project-dir | ./ghidra-projects | Directory for Ghidra projects | | --project-name | mcp_project | Ghidra project name |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | GHIDRA_INSTALL_DIR | (auto-detect) | Path to Ghidra installation directory (required if PyGhidra auto-detection fails) | | GHIDRA_ANALYSIS_TIMEOUT_SECONDS | 300 | Analysis timeout per binary | | GHIDRA_MAX_HEAP | 2g | JVM max heap size |

Docker Volumes

| Path | Purpose | |------|---------| | /home/ghidra/binaries | Input binaries (mounted read-only) | | /home/ghidra/projects | Persistent Ghidra project data |

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (uses mocked GhidraBridge, no Ghidra needed)
pytest tests/ -v

# 192 tests covering full mode, emulation, server, code mode, script mode, CLI, and validation

Architecture

MCP Client (Claude Desktop / Claude Code / OpenCode / Continue.dev / ...)
  ↕ stdio or SSE (HTTP)
FastMCP Server (server.py)
  ├── Full Mode: 32 @mcp.tool() + 5 @mcp.resource()
  ├── Code Mode: search + execute → _dispatch()
  └── Script Mode: search_api + get_class_info + execute_script
        ↕
GhidraBridge (ghidra_bridge.py)
  ├── Programs cache     (dict[str, Program])
  ├── Decompilers cache  (dict[str, DecompInterface])
  └── Emulators cache    (dict[str, EmulatorHelper])
        ↕
PyGhidra / JPype / JVM
        ↕
Ghidra Java API

• FastMCP handles MCP protocol over stdio or SSE
• GhidraBridge manages the JVM lifecycle, Ghidra project, cached program handles, decompiler instances, and emulator sessions
• PyGhidra provides in-process access to Ghidra's Java API via JPype (no separate Ghidra process needed)
• Code Mode dispatcher (_dispatch) translates execute(method, params) calls into the appropriate bridge method invocations, handling parameter renaming and response wrapping

License

MIT