GhidrAssistMCP

1# GhidrAssistMCP
2 
3A 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.
4 
5## Overview
6 
7GhidrAssistMCP 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.
8 
9### Key Features
10 
11- **MCP Server Integration**: Full Model Context Protocol server implementation using official SDK
12- **Dual HTTP Transports**: Supports SSE and Streamable HTTP transports for maximum client compatibility
13- **34 Built-in Tools**: Comprehensive set of analysis tools with action-based consolidation for cleaner APIs
14- **5 MCP Resources**: Static data resources for program info, functions, strings, imports, and exports
15- **5 MCP Prompts**: Pre-built analysis prompts for common reverse engineering tasks
16- **Result Caching**: Intelligent caching system to improve performance for repeated queries
17- **Async Task Support**: Long-running operations execute asynchronously with task management
18- **Multi-Program Support**: Work with multiple open programs simultaneously using `program_name` parameter
19- **Multi-Window Support**: Single MCP server shared across all CodeBrowser windows with intelligent focus tracking
20- **Active Context Awareness**: Automatic detection of which binary window is in focus, with context hints in all tool responses
21- **Configurable UI**: Easy-to-use interface for managing tools and monitoring activity
22- **Real-time Logging**: Track all MCP requests and responses with detailed logging
23- **Dynamic Tool Management**: Enable/disable tools individually with persistent settings
24 
25## Clients
26 
27Shameless self-promotion: [GhidrAssist](https://github.com/jtang613/GhidrAssist) supports GhidrAssistMCP right out of the box.
28 
29## Screenshots
30 
31![Screenshot](https://github.com/jtang613/GhidrAssistMCP/blob/master/res/Screenshot1.png)
32![Screenshot](https://github.com/jtang613/GhidrAssistMCP/blob/master/res/Screenshot2.png)
33 
34## Installation
35 
36### Prerequisites
37 
38- **Ghidra 11.4+** (tested with Ghidra 12.0 Public)
39- **An MCP Client (Like GhidrAssist)**
40 
41### Binary Release (Recommended)
42 
431. **Download the latest release**:
44   - Go to the [Releases page](https://github.com/jtang613/GhidrAssistMCP/releases)
45   - Download the latest `.zip` file (e.g., `GhidrAssistMCP-v1.0.0.zip`)
46 
472. **Install the extension**:
48   - In Ghidra: **File → Install Extensions → Add Extension**
49   - Select the downloaded ZIP file
50   - Restart Ghidra when prompted
51 
523. **Enable the plugin**:
53   - **File → Configure → Configure Plugins**
54   - Search for "GhidrAssistMCP"
55   - Check the box to enable the plugin
56 
57### Building from Source
58 
591. **Clone the repository**:
60 
61   ```bash
62   git clone <repository-url>
63   cd GhidrAssistMCP
64   ```
65 
662. **Point Gradle at your Ghidra install**:
67   - Set `GHIDRA_INSTALL_DIR` (environment variable), or pass `-PGHIDRA_INSTALL_DIR=<path>` when you run Gradle.
68 
693. **Build + install**:
70 
71   Ensure Ghidra isn't running and run:
72 
73   ```bash
74   gradle installExtension
75   ```
76 
77   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).
78 
79   If you need to override that location, pass `-PGHIDRA_USER_EXTENSIONS_DIR=<path>`.
80 
814. **Restart / verify**:
82   - Restart Ghidra.
83   - If the plugin doesn't appear, enable it via **File → Configure → Configure Plugins** (search for "GhidrAssistMCP").
84 
85## Configuration
86 
87### Initial Setup
88 
891. **Open the Control Panel**:
90   - Window → GhidrAssistMCP (or use the toolbar icon)
91 
922. **Configure Server Settings**:
93   - **Host**: Default is `localhost`
94   - **Port**: Default is `8080`
95   - **Enable/Disable**: Toggle the MCP server on/off
96 
97### Tool Management
98 
99The Configuration tab allows you to:
100 
101- **View all available tools** (34 total)
102- **Enable/disable individual tools** using checkboxes
103- **Save configuration** to persist across sessions
104- **Monitor tool status** in real-time
105 
106## Available Tools
107 
108GhidrAssistMCP provides 34 tools organized into categories. Several tools use an action-based API pattern where a single tool provides multiple related operations.
109 
110### Program & Data Listing
111 
112| Tool | Description |
113| ---- | ----------- |
114| `get_program_info` | Get basic program information (name, architecture, compiler, etc.) |
115| `list_programs` | List all open programs across all CodeBrowser windows |
116| `list_functions` | List functions with optional pattern filtering and pagination |
117| `list_data` | List data definitions in the program |
118| `list_data_types` | List all available data types |
119| `list_strings` | List string references with optional filtering |
120| `list_imports` | List imported functions/symbols |
121| `list_exports` | List exported functions/symbols |
122| `list_segments` | List memory segments |
123| `list_namespaces` | List namespaces in the program |
124| `list_relocations` | List relocation entries |
125 
126### Function & Code Analysis
127 
128| Tool | Description |
129| ---- | ----------- |
130| `get_function_info` | Get detailed function information (signature, variables, etc.) |
131| `get_current_function` | Get function at current cursor position |
132| `get_current_address` | Get current cursor address |
133| `get_hexdump` | Get hexdump of memory at specific address |
134| `get_call_graph` | Get call graph for a function (callers and callees) |
135| `get_basic_blocks` | Get basic block information for a function |
136 
137### Consolidated Tools
138 
139These tools bundle related operations behind a discriminator parameter (e.g., `action`, `target`, `target_type`, or `format`).
140 
141#### `get_code` - Code Retrieval Tool
142 
143| Parameter | Values | Description |
144| --------- | ------ | ----------- |
145| `format` | `decompiler`, `disassembly`, `pcode` | Output format |
146| `raw` | boolean | Only affects `format: "pcode"` (raw pcode ops vs grouped by basic blocks) |
147 
148#### `class` - Class Operations Tool
149 
150| Action | Description |
151| ------ | ----------- |
152| `list` | List classes with optional pattern filtering and pagination |
153| `get_info` | Get detailed class information (methods, fields, vtables, virtual functions) |
154 
155#### `xrefs` - Cross-Reference Tool
156 
157| Parameter | Description |
158| --------- | ----------- |
159| `address` | Find all references to/from a specific address |
160| `function` | Find all cross-references for a function |
161 
162#### `struct` - Structure Operations Tool
163 
164| Action | Description |
165| ------ | ----------- |
166| `create` | Create a new structure from C definition or empty |
167| `modify` | Modify an existing structure with new C definition |
168| `merge` | Merge (overlay) fields from a C definition onto an existing structure without deleting existing fields |
169| `set_field` | Set/insert a single field at a specific offset without needing a full C struct (use `field_name` to name it) |
170| `name_gap` | Convert undefined bytes at an offset/length into a named `byte[]`-like field (useful for “naming gaps”; uses `field_name`) |
171| `auto_create` | Automatically create structure from variable usage patterns |
172| `rename_field` | Rename a field within a structure |
173| `field_xrefs` | Find cross-references to a specific struct field |
174 
175#### `rename_symbol` - Symbol Renaming Tool
176 
177| Parameter | Values | Description |
178| --------- | ------ | ----------- |
179| `target_type` | `function`, `data`, `variable` | What kind of symbol to rename |
180 
181#### `set_comment` - Comment Tool
182 
183| Parameter | Values | Description |
184| --------- | ------ | ----------- |
185| `target` | `function`, `address` | Where to set the comment |
186| `comment_type` | `eol`, `pre`, `post`, `plate`, `repeatable` | Comment type for `target: "address"` (default `eol`) |
187 
188#### `bookmarks` - Bookmark Management Tool
189 
190| Action | Description |
191| ------ | ----------- |
192| `list` | List all bookmarks |
193| `add` | Add a new bookmark |
194| `delete` | Delete a bookmark |
195 
196### Type & Prototype Tools
197 
198| Tool | Description |
199| ----- | ----------- |
200| `get_data_type` | Get detailed data type information and structure definitions |
201| `delete_data_type` | Delete a data type by name (optionally scoped by `category`) |
202| `set_data_type` | Set data type at a specific address |
203| `set_function_prototype` | Set function signature/prototype |
204| `set_local_variable_type` | Set data type for local variables |
205 
206### Search Tools
207 
208| Tool | Description |
209| ----- | ----------- |
210| `search_bytes` | Search for byte patterns in memory |
211 
212### Async Task Management
213 
214Long-running operations (decompilation, structure analysis, field xrefs) execute asynchronously:
215 
216| Tool | Description |
217| ---- | ----------- |
218| `get_task_status` | Check status and retrieve results of async tasks |
219| `cancel_task` | Cancel a running async task |
220| `list_tasks` | List all pending/running/completed tasks |
221 
222## MCP Resources
223 
224GhidrAssistMCP exposes 5 static resources that can be read by MCP clients:
225 
226| Resource URI | Description |
227| ------------ | ----------- |
228| `ghidra://program/info` | Basic program information |
229| `ghidra://program/functions` | List of all functions |
230| `ghidra://program/strings` | String references |
231| `ghidra://program/imports` | Imported symbols |
232| `ghidra://program/exports` | Exported symbols |
233 
234## MCP Prompts
235 
236Pre-built prompts for common analysis tasks:
237 
238| Prompt | Description |
239| ------ | ----------- |
240| `analyze_function` | Comprehensive function analysis prompt |
241| `identify_vulnerability` | Security vulnerability identification |
242| `document_function` | Generate function documentation |
243| `trace_data_flow` | Data flow analysis prompt |
244| `trace_network_data` | Trace network send/recv call stacks for protocol analysis and network vulnerability identification |
245 
246## Usage Examples
247 
248### Basic Program Information
249 
250```json
251{
252  "method": "tools/call",
253  "params": {
254    "name": "get_program_info"
255  }
256}
257```
258 
259### List Functions with Pattern Filtering
260 
261```json
262{
263  "method": "tools/call",
264  "params": {
265    "name": "list_functions",
266    "arguments": {
267      "pattern": "init",
268      "case_sensitive": false,
269      "limit": 50
270    }
271  }
272}
273```
274 
275### Decompile Function (`get_code`)
276 
277```json
278{
279  "method": "tools/call",
280  "params": {
281    "name": "get_code",
282    "arguments": {
283      "function": "main",
284      "format": "decompiler"
285    }
286  }
287}
288```
289 
290### Get Class Information (Action-Based)
291 
292```json
293{
294  "method": "tools/call",
295  "params": {
296    "name": "class",
297    "arguments": {
298      "action": "get_info",
299      "class_name": "MyClass"
300    }
301  }
302}
303```
304 
305### Search Classes (Action-Based)
306 
307```json
308{
309  "method": "tools/call",
310  "params": {
311    "name": "class",
312    "arguments": {
313      "action": "list",
314      "pattern": "Socket",
315      "case_sensitive": false
316    }
317  }
318}
319```
320 
321### Auto-Create Structure (Action-Based)
322 
323```json
324{
325  "method": "tools/call",
326  "params": {
327    "name": "struct",
328    "arguments": {
329      "action": "auto_create",
330      "function_identifier": "0x00401000",
331      "variable_name": "ctx"
332    }
333  }
334}
335```
336 
337### Find Struct Field Cross-References (Action-Based)
338 
339```json
340{
341  "method": "tools/call",
342  "params": {
343    "name": "struct",
344    "arguments": {
345      "action": "field_xrefs",
346      "structure_name": "Host",
347      "field_name": "port"
348    }
349  }
350}
351```
352 
353### Delete a Data Type
354 
355If multiple types share the same name across categories, pass `category` (or pass a full path in `name` starting with `/`).
356 
357```json
358{
359  "method": "tools/call",
360  "params": {
361    "name": "delete_data_type",
362    "arguments": {
363      "name": "MyStruct",
364      "category": "/mytypes"
365    }
366  }
367}
368```
369 
370### Rename Function (Action-Based)
371 
372```json
373{
374  "method": "tools/call",
375  "params": {
376    "name": "rename_symbol",
377    "arguments": {
378      "action": "function",
379      "address": "0x00401000",
380      "new_name": "decrypt_buffer"
381    }
382  }
383}
384```
385 
386### Multi-Program Support
387 
388When working with multiple open programs, first list them:
389 
390```json
391{
392  "method": "tools/call",
393  "params": {
394    "name": "list_programs"
395  }
396}
397```
398 
399Then specify which program to target using `program_name`:
400 
401```json
402{
403  "method": "tools/call",
404  "params": {
405    "name": "list_functions",
406    "arguments": {
407      "program_name": "target_binary.exe",
408      "limit": 10
409    }
410  }
411}
412```
413 
414## Multi-Window Support & Active Context Awareness
415 
416GhidrAssistMCP uses a singleton architecture that enables seamless operation across multiple CodeBrowser windows:
417 
418### How It Works
419 
4201. **Single Shared Server**: One MCP server (port 8080) serves all CodeBrowser windows
4212. **Focus Tracking**: Automatically detects which CodeBrowser window is currently active
4223. **Context Hints**: All tool responses include context information to help AI understand which binary is in focus
423 
424### Context Information in Responses
425 
426Every tool response includes a context header:
427 
428```plaintext
429[Context] Operating on: malware.exe | Active window: malware.exe
430 
431<tool response content>
432```
433 
434or when targeting a different program:
435 
436```plaintext
437[Context] Operating on: lib.so | Active window: main.exe | Total open programs: 3
438 
439<tool response content>
440```
441 
442### Benefits for AI Assistants
443 
444- **Smart Defaults**: When no `program_name` is specified, tools automatically use the program from the active window
445- **Context Awareness**: AI knows which binary the user is currently viewing
446- **Prevents Confusion**: Clear indication when operating on a different binary than what's in the active window
447- **Multi-tasking**: Work with multiple binaries without constantly specifying which one to target
448 
449## Architecture
450 
451### Core Components
452 
453```plaintext
454GhidrAssistMCP/
455├── GhidrAssistMCPManager     # Singleton coordinator for multi-window support
456│   ├── Tracks all CodeBrowser windows
457│   ├── Manages focus tracking
458│   └── Owns shared server and backend
459├── GhidrAssistMCPPlugin      # Plugin instance (one per CodeBrowser window)
460│   └── Registers with singleton manager
461├── GhidrAssistMCPServer      # HTTP MCP server (SSE + Streamable)
462│   └── Single shared instance on port 8080
463├── GhidrAssistMCPBackend     # Tool management and execution
464│   ├── Tool registry with enable/disable states
465│   ├── Result caching system
466│   ├── Async task management
467│   └── Resource and prompt registries
468├── GhidrAssistMCPProvider    # UI component provider
469│   └── First registered instance provides UI
470├── cache/                    # Caching infrastructure
471│   ├── McpCache.java
472│   └── CacheEntry.java
473├── tasks/                    # Async task management
474│   ├── McpTaskManager.java
475│   └── McpTask.java
476├── resources/                # MCP Resources (5 total)
477│   ├── ProgramInfoResource.java
478│   ├── FunctionListResource.java
479│   ├── StringsResource.java
480│   ├── ImportsResource.java
481│   └── ExportsResource.java
482├── prompts/                  # MCP Prompts (5 total)
483│   ├── AnalyzeFunctionPrompt.java
484│   ├── IdentifyVulnerabilityPrompt.java
485│   ├── DocumentFunctionPrompt.java
486│   ├── TraceDataFlowPrompt.java
487│   └── TraceNetworkDataPrompt.java
488└── tools/                    # MCP Tools (34 total)
489    ├── Consolidated action-based tools
490    ├── Analysis tools
491    ├── Modification tools
492    └── Navigation tools
493```
494 
495### Tool Design Patterns
496 
497**Consolidated Tools**: Related operations are consolidated into single tools with a discriminator parameter:
498 
499- `get_code`: `format: decompiler|disassembly|pcode`
500- `class`: `action: list|get_info`
501- `struct`: `action: create|modify|auto_create|rename_field|field_xrefs`
502- `rename_symbol`: `target_type: function|data|variable`
503- `set_comment`: `target: function|address`
504- `bookmarks`: `action: list|add|delete`
505 
506**Tool Interface Methods**:
507 
508- `isReadOnly()`: Indicates if tool modifies program state
509- `isLongRunning()`: Triggers async execution with task management
510- `isCacheable()`: Enables result caching for repeated queries
511- `isDestructive()`: Marks potentially dangerous operations
512- `isIdempotent()`: Indicates if repeated calls produce same result
513 
514### MCP Protocol Implementation
515 
516- **Transports**:
517  - HTTP with Server-Sent Events (SSE)
518  - Streamable HTTP
519- **Endpoints**:
520  - `GET /sse` - SSE connection for bidirectional communication
521  - `POST /message` - Message exchange endpoint
522  - `GET /mcp` - Receive Streamable HTTP events
523  - `POST /mcp` - Initialize Streamable HTTP session
524  - `DELETE /mcp` - Terminate Streamable HTTP session
525- **Capabilities**: Tools, Resources, Prompts
526 
527## Development
528 
529### Project Structure
530 
531```plaintext
532src/main/java/ghidrassistmcp/
533├── GhidrAssistMCPPlugin.java      # Main plugin class
534├── GhidrAssistMCPManager.java     # Singleton coordinator
535├── GhidrAssistMCPProvider.java    # UI provider with tabs
536├── GhidrAssistMCPServer.java      # MCP server implementation
537├── GhidrAssistMCPBackend.java     # Backend tool/resource/prompt management
538├── McpBackend.java                # Backend interface
539├── McpTool.java                   # Tool interface
540├── McpEventListener.java          # Event notification interface
541├── cache/                         # Caching system
542├── tasks/                         # Async task system
543├── resources/                     # MCP resources
544├── prompts/                       # MCP prompts
545└── tools/                         # Tool implementations (34 files)
546```
547 
548### Adding New Tools
549 
5501. **Implement McpTool interface**:
551 
552   ```java
553   public class MyCustomTool implements McpTool {
554       @Override
555       public String getName() { return "my_custom_tool"; }
556 
557       @Override
558       public String getDescription() { return "Description"; }
559 
560       @Override
561       public boolean isReadOnly() { return true; }
562 
563       @Override
564       public boolean isLongRunning() { return false; }
565 
566       @Override
567       public boolean isCacheable() { return true; }
568 
569       @Override
570       public McpSchema.JsonSchema getInputSchema() { /* ... */ }
571 
572       @Override
573       public McpSchema.CallToolResult execute(Map<String, Object> arguments, Program program) {
574           // Implementation
575       }
576   }
577   ```
578 
5792. **Register in backend**:
580 
581   ```java
582   // In GhidrAssistMCPBackend constructor
583   registerTool(new MyCustomTool());
584   ```
585 
586### Build Commands
587 
588```bash
589# Clean build
590gradle clean
591 
592# Build extension zip (written to dist/)
593gradle buildExtension
594 
595# Install (extract) extension into the Ghidra user Extensions directory
596gradle installExtension
597 
598# Uninstall (delete extracted directory from the Ghidra user Extensions directory)
599gradle uninstallExtension
600 
601# Build/install with specific Ghidra path (required if GHIDRA_INSTALL_DIR isn't set)
602gradle -PGHIDRA_INSTALL_DIR=/path/to/ghidra installExtension
603 
604# Debug build
605gradle buildExtension --debug
606```
607 
608### Dependencies
609 
610- **MCP SDK**: `io.modelcontextprotocol.sdk:mcp:0.17.1`
611- **Jetty Server**: `11.0.20` (HTTP/SSE transport)
612- **Jackson**: `2.18.3` (JSON processing)
613- **Ghidra API**: Bundled with Ghidra installation
614 
615## Logging
616 
617### UI Logging
618 
619The **Log** tab provides real-time monitoring:
620 
621- **Session Events**: Server start/stop, program changes
622- **Tool Requests**: `REQ: tool_name {parameters...}`
623- **Tool Responses**: `RES: tool_name {response...}`
624- **Error Messages**: Failed operations and diagnostics
625- **Cache Hits**: When cached results are returned
626 
627### Console Logging
628 
629Detailed logging in Ghidra's console:
630 
631- Tool registration and initialization
632- MCP server lifecycle events
633- Async task execution and completion
634- Cache statistics
635- Database transaction operations
636- Error stack traces and debugging information
637 
638## Troubleshooting
639 
640### Common Issues
641 
642#### Server Won't Start
643 
644- Check if port 8080 is available
645- Verify Ghidra installation path
646- Examine console logs for errors
647 
648#### Tools Not Appearing
649 
650- Ensure plugin is enabled
651- Check Configuration tab for tool status
652- Verify backend initialization in logs
653 
654#### MCP Client Connection Issues
655 
656- Confirm server is running (check GhidrAssistMCP window)
657- Test connection: `curl http://localhost:8080/sse`
658- Check firewall settings
659 
660#### Tool Execution Failures
661 
662- Verify program is loaded in Ghidra
663- Check tool parameters are correct
664- Review error messages in Log tab
665 
666#### Async Task Issues
667 
668- Use `get_task_status` to check task state
669- Use `list_tasks` to see all tasks
670- Use `cancel_task` if a task is stuck
671 
672### Debug Mode
673 
674Enable debug logging by adding to Ghidra startup:
675 
676```bash
677-Dlog4j.logger.ghidrassistmcp=DEBUG
678```
679 
680## Contributing
681 
6821. **Fork the repository**
6832. **Create a feature branch**: `git checkout -b feature-name`
6843. **Make your changes** with proper tests
6854. **Follow code style**: Use existing patterns and conventions
6865. **Submit a pull request** with detailed description
687 
688### Code Standards
689 
690- **Java 21+ features** where appropriate
691- **Proper exception handling** with meaningful messages
692- **Transaction safety** for all database operations
693- **Thread safety** for UI operations
694- **Comprehensive documentation** for public APIs
695- **Action-based consolidation** for related tool operations
696 
697## License
698 
699This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
700 
701## Acknowledgments
702 
703- **NSA/Ghidra Team** for the excellent reverse engineering platform
704- **Anthropic** for the Model Context Protocol specification
705 
706---
707 
708**Questions or Issues?**
709 
710Please open an issue on the project repository for bug reports, feature requests, or questions about usage and development.
711