SymGraph

On this page

GhidrAssistMCP

A powerful Ghidra extension that provides an MCP (Model Context Protocol) server, enabling AI assistants and other tools to interact with Ghidra’s reverse engineering capabilities through a standardized API.

Overview

GhidrAssistMCP bridges the gap between AI-powered analysis tools and Ghidra’s comprehensive reverse engineering platform. By implementing the Model Context Protocol, this extension allows external AI assistants, automated analysis tools, and custom scripts to seamlessly interact with Ghidra’s analysis capabilities.

Key Features

Clients

Shameless self-promotion: GhidrAssist supports GhidrAssistMCP right out of the box.

Screenshots

Screenshot Screenshot

Installation

Prerequisites

  1. Download the latest release:
    • Go to the Releases page
    • Download the latest .zip file (e.g., GhidrAssistMCP-v1.0.0.zip)
  2. Install the extension:
    • In Ghidra: File → Install Extensions → Add Extension
    • Select the downloaded ZIP file
    • Restart Ghidra when prompted
  3. Enable the plugin:
    • File → Configure → Configure Plugins
    • Search for “GhidrAssistMCP”
    • Check the box to enable the plugin

Building from Source

  1. Clone the repository:

    git clone <repository-url>
cd GhidrAssistMCP

  2. Point Gradle at your Ghidra install:

    • Set GHIDRA_INSTALL_DIR (environment variable), or pass -PGHIDRA_INSTALL_DIR=<path> when you run Gradle.

  3. Build + install:

    Ensure Ghidra isn’t running and run:

    gradle installExtension

    This copies the built ZIP into your Ghidra install ([GHIDRA_INSTALL_DIR]/Extensions/Ghidra) and extracts it into your Ghidra user Extensions folder (replacing any existing extracted copy).

    If you need to override that location, pass -PGHIDRA_USER_EXTENSIONS_DIR=<path>.

  4. Restart / verify:

    • Restart Ghidra.
    • If the plugin doesn’t appear, enable it via File → Configure → Configure Plugins (search for “GhidrAssistMCP”).

Configuration

Initial Setup

  1. Open the Control Panel:
    • Window → GhidrAssistMCP (or use the toolbar icon)
  2. Configure Server Settings:
    • Host: Default is localhost
    • Port: Default is 8080
    • Enable/Disable: Toggle the MCP server on/off

Tool Management

The Configuration tab allows you to:

Available Tools

GhidrAssistMCP provides 34 tools organized into categories. Several tools use an action-based API pattern where a single tool provides multiple related operations.

Program & Data Listing

Tool Description
get_program_info Get basic program information (name, architecture, compiler, etc.)
list_programs List all open programs across all CodeBrowser windows
list_functions List functions with optional pattern filtering and pagination
list_data List data definitions in the program
list_data_types List all available data types
list_strings List string references with optional filtering
list_imports List imported functions/symbols
list_exports List exported functions/symbols
list_segments List memory segments
list_namespaces List namespaces in the program
list_relocations List relocation entries

Function & Code Analysis

Tool Description
get_function_info Get detailed function information (signature, variables, etc.)
get_current_function Get function at current cursor position
get_current_address Get current cursor address
get_hexdump Get hexdump of memory at specific address
get_call_graph Get call graph for a function (callers and callees)
get_basic_blocks Get basic block information for a function

Consolidated Tools

These tools bundle related operations behind a discriminator parameter (e.g., action, target, target_type, or format).

get_code - Code Retrieval Tool

Parameter Values Description
format decompiler, disassembly, pcode Output format
raw boolean Only affects format: "pcode" (raw pcode ops vs grouped by basic blocks)

class - Class Operations Tool

Action Description
list List classes with optional pattern filtering and pagination
get_info Get detailed class information (methods, fields, vtables, virtual functions)

xrefs - Cross-Reference Tool

Parameter Description
address Find all references to/from a specific address
function Find all cross-references for a function

struct - Structure Operations Tool

Action Description
create Create a new structure from C definition or empty
modify Modify an existing structure with new C definition
merge Merge (overlay) fields from a C definition onto an existing structure without deleting existing fields
set_field Set/insert a single field at a specific offset without needing a full C struct (use field_name to name it)
name_gap Convert undefined bytes at an offset/length into a named byte[]-like field (useful for “naming gaps”; uses field_name)
auto_create Automatically create structure from variable usage patterns
rename_field Rename a field within a structure
field_xrefs Find cross-references to a specific struct field

rename_symbol - Symbol Renaming Tool

Parameter Values Description
target_type function, data, variable What kind of symbol to rename

set_comment - Comment Tool

Parameter Values Description
target function, address Where to set the comment
comment_type eol, pre, post, plate, repeatable Comment type for target: "address" (default eol)

bookmarks - Bookmark Management Tool

Action Description
list List all bookmarks
add Add a new bookmark
delete Delete a bookmark

Type & Prototype Tools

Tool Description
get_data_type Get detailed data type information and structure definitions
delete_data_type Delete a data type by name (optionally scoped by category)
set_data_type Set data type at a specific address
set_function_prototype Set function signature/prototype
set_local_variable_type Set data type for local variables

Search Tools

Tool Description
search_bytes Search for byte patterns in memory

Async Task Management

Long-running operations (decompilation, structure analysis, field xrefs) execute asynchronously:

Tool Description
get_task_status Check status and retrieve results of async tasks
cancel_task Cancel a running async task
list_tasks List all pending/running/completed tasks

MCP Resources

GhidrAssistMCP exposes 5 static resources that can be read by MCP clients:

Resource URI Description
ghidra://program/info Basic program information
ghidra://program/functions List of all functions
ghidra://program/strings String references
ghidra://program/imports Imported symbols
ghidra://program/exports Exported symbols

MCP Prompts

Pre-built prompts for common analysis tasks:

Prompt Description
analyze_function Comprehensive function analysis prompt
identify_vulnerability Security vulnerability identification
document_function Generate function documentation
trace_data_flow Data flow analysis prompt
trace_network_data Trace network send/recv call stacks for protocol analysis and network vulnerability identification

Usage Examples

Basic Program Information

{
  "method": "tools/call",
  "params": {
    "name": "get_program_info"
  }
}

List Functions with Pattern Filtering

{
  "method": "tools/call",
  "params": {
    "name": "list_functions",
    "arguments": {
      "pattern": "init",
      "case_sensitive": false,
      "limit": 50
    }
  }
}

Decompile Function (get_code)

{
  "method": "tools/call",
  "params": {
    "name": "get_code",
    "arguments": {
      "function": "main",
      "format": "decompiler"
    }
  }
}

Get Class Information (Action-Based)

{
  "method": "tools/call",
  "params": {
    "name": "class",
    "arguments": {
      "action": "get_info",
      "class_name": "MyClass"
    }
  }
}

Search Classes (Action-Based)

{
  "method": "tools/call",
  "params": {
    "name": "class",
    "arguments": {
      "action": "list",
      "pattern": "Socket",
      "case_sensitive": false
    }
  }
}

Auto-Create Structure (Action-Based)

{
  "method": "tools/call",
  "params": {
    "name": "struct",
    "arguments": {
      "action": "auto_create",
      "function_identifier": "0x00401000",
      "variable_name": "ctx"
    }
  }
}

Find Struct Field Cross-References (Action-Based)

{
  "method": "tools/call",
  "params": {
    "name": "struct",
    "arguments": {
      "action": "field_xrefs",
      "structure_name": "Host",
      "field_name": "port"
    }
  }
}

Delete a Data Type

If multiple types share the same name across categories, pass category (or pass a full path in name starting with /).

{
  "method": "tools/call",
  "params": {
    "name": "delete_data_type",
    "arguments": {
      "name": "MyStruct",
      "category": "/mytypes"
    }
  }
}

Rename Function (Action-Based)

{
  "method": "tools/call",
  "params": {
    "name": "rename_symbol",
    "arguments": {
      "action": "function",
      "address": "0x00401000",
      "new_name": "decrypt_buffer"
    }
  }
}

Multi-Program Support

When working with multiple open programs, first list them:

{
  "method": "tools/call",
  "params": {
    "name": "list_programs"
  }
}

Then specify which program to target using program_name:

{
  "method": "tools/call",
  "params": {
    "name": "list_functions",
    "arguments": {
      "program_name": "target_binary.exe",
      "limit": 10
    }
  }
}

Multi-Window Support & Active Context Awareness

GhidrAssistMCP uses a singleton architecture that enables seamless operation across multiple CodeBrowser windows:

How It Works

  1. Single Shared Server: One MCP server (port 8080) serves all CodeBrowser windows
  2. Focus Tracking: Automatically detects which CodeBrowser window is currently active
  3. Context Hints: All tool responses include context information to help AI understand which binary is in focus

Context Information in Responses

Every tool response includes a context header:

[Context] Operating on: malware.exe | Active window: malware.exe

<tool response content>

or when targeting a different program:

[Context] Operating on: lib.so | Active window: main.exe | Total open programs: 3

<tool response content>

Benefits for AI Assistants

Architecture

Core Components

GhidrAssistMCP/
├── GhidrAssistMCPManager     # Singleton coordinator for multi-window support
│   ├── Tracks all CodeBrowser windows
│   ├── Manages focus tracking
│   └── Owns shared server and backend
├── GhidrAssistMCPPlugin      # Plugin instance (one per CodeBrowser window)
│   └── Registers with singleton manager
├── GhidrAssistMCPServer      # HTTP MCP server (SSE + Streamable)
│   └── Single shared instance on port 8080
├── GhidrAssistMCPBackend     # Tool management and execution
│   ├── Tool registry with enable/disable states
│   ├── Result caching system
│   ├── Async task management
│   └── Resource and prompt registries
├── GhidrAssistMCPProvider    # UI component provider
│   └── First registered instance provides UI
├── cache/                    # Caching infrastructure
│   ├── McpCache.java
│   └── CacheEntry.java
├── tasks/                    # Async task management
│   ├── McpTaskManager.java
│   └── McpTask.java
├── resources/                # MCP Resources (5 total)
│   ├── ProgramInfoResource.java
│   ├── FunctionListResource.java
│   ├── StringsResource.java
│   ├── ImportsResource.java
│   └── ExportsResource.java
├── prompts/                  # MCP Prompts (5 total)
│   ├── AnalyzeFunctionPrompt.java
│   ├── IdentifyVulnerabilityPrompt.java
│   ├── DocumentFunctionPrompt.java
│   ├── TraceDataFlowPrompt.java
│   └── TraceNetworkDataPrompt.java
└── tools/                    # MCP Tools (34 total)
    ├── Consolidated action-based tools
    ├── Analysis tools
    ├── Modification tools
    └── Navigation tools

Tool Design Patterns

Consolidated Tools: Related operations are consolidated into single tools with a discriminator parameter:

Tool Interface Methods:

MCP Protocol Implementation

Development

Project Structure

src/main/java/ghidrassistmcp/
├── GhidrAssistMCPPlugin.java      # Main plugin class
├── GhidrAssistMCPManager.java     # Singleton coordinator
├── GhidrAssistMCPProvider.java    # UI provider with tabs
├── GhidrAssistMCPServer.java      # MCP server implementation
├── GhidrAssistMCPBackend.java     # Backend tool/resource/prompt management
├── McpBackend.java                # Backend interface
├── McpTool.java                   # Tool interface
├── McpEventListener.java          # Event notification interface
├── cache/                         # Caching system
├── tasks/                         # Async task system
├── resources/                     # MCP resources
├── prompts/                       # MCP prompts
└── tools/                         # Tool implementations (34 files)

Adding New Tools

  1. Implement McpTool interface:

    public class MyCustomTool implements McpTool {
    @Override
    public String getName() { return "my_custom_tool"; }

    @Override
    public String getDescription() { return "Description"; }

    @Override
    public boolean isReadOnly() { return true; }

    @Override
    public boolean isLongRunning() { return false; }

    @Override
    public boolean isCacheable() { return true; }

    @Override
    public McpSchema.JsonSchema getInputSchema() { /* ... */ }

    @Override
    public McpSchema.CallToolResult execute(Map<String, Object> arguments, Program program) {
        // Implementation
    }
}

  2. Register in backend:

    // In GhidrAssistMCPBackend constructor
registerTool(new MyCustomTool());

Build Commands

# Clean build
gradle clean

# Build extension zip (written to dist/)
gradle buildExtension

# Install (extract) extension into the Ghidra user Extensions directory
gradle installExtension

# Uninstall (delete extracted directory from the Ghidra user Extensions directory)
gradle uninstallExtension

# Build/install with specific Ghidra path (required if GHIDRA_INSTALL_DIR isn't set)
gradle -PGHIDRA_INSTALL_DIR=/path/to/ghidra installExtension

# Debug build
gradle buildExtension --debug

Dependencies

Logging

UI Logging

The Log tab provides real-time monitoring:

Console Logging

Detailed logging in Ghidra’s console:

Troubleshooting

Common Issues

Server Won’t Start

Tools Not Appearing

MCP Client Connection Issues

Tool Execution Failures

Async Task Issues

Debug Mode

Enable debug logging by adding to Ghidra startup:

-Dlog4j.logger.ghidrassistmcp=DEBUG

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes with proper tests
  4. Follow code style: Use existing patterns and conventions
  5. Submit a pull request with detailed description

Code Standards

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Questions or Issues?

Please open an issue on the project repository for bug reports, feature requests, or questions about usage and development.