Skip to content
Back to search

GhydraMCP

Ghidra plugin exposing a HATEOAS REST API, with a Python MCP bridge and CLI for AI-assisted reverse engineering: multi-instance decompilation, disassembly, and binary analysis. Supports Ghidra 11.x and 12.x.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/starsong-consulting--ghydramcp/badge.svg)](/listings/starsong-consulting--ghydramcp)

HTML

<a href="/listings/starsong-consulting--ghydramcp"><img src="/api/listings/starsong-consulting--ghydramcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [Ghidra](https://ghidra-sre.org) 11.x or 12.x. Releases ship a separate build per Ghidra version; the extension's `ghidraVersion` must match your Ghidra version exactly. - Java 21 (Temurin 21 recommended) for building the plugin - Python3 - MCP [SDK](https://github.com/modelcontextprotocol/python-sdk)

Ghidra

First, download the latest [release](https://github.com/starsong-consulting/GhydraMCP/releases) from this repository. The "Complete" artifact contains the zipped Ghidra plugin and the Python MCP bridge. Unpack the outer archive, then, add the plugin to Ghidra:

1. Run Ghidra 2. Select `File` -> `Install Extensions` 3. Click the `+` button 4. Select the `Ghydra-*-ghidra<version>.zip` that matches your Ghidra version (e.g. `...-ghidra12.1.2.zip` for Ghidra 12.1.2) 5. Restart Ghidra 6. Make sure the Ghydra plugin is enabled in `File` -> `Configure` -> `Developer`

> **Note:** By default, the first CodeBrowser opened in Ghidra gets port 8192, the second gets 8193, and so on. You can check which ports are being used by looking at the Console in the Ghidra main (project) window - click the computer icon in the bottom right to "Open Console". Look for log entries like: > ``` > (GhydraPlugin) GhydraMCP loaded on port 8193 > (GhydraServer) GhydraMCP HTTP server started on port 8193 > ``` > > GhydraMCP now includes auto-discovery of running Ghidra instances, so manually registering each instance is typically not necessary. The MCP bridge will automatically discover and register instances on startup and periodically check for new ones.

Video Installation Guide:

https://github.com/user-attachments/assets/75f0c176-6da1-48dc-ad96-c182eb4648c3

CLI Tool

GhydraMCP includes `ghydra`, a command-line tool for interacting with Ghidra directly from the terminal. It works standalone, no MCP client needed.

# Install
pip install -e .

# List running Ghidra instances
ghydra instances list

# Decompile a function
ghydra functions decompile --name main

# List strings matching a pattern
ghydra data list-strings --filter "password"

# Read memory as hex dump
ghydra memory read --address 0x401000 --length 64

# JSON output for scripting and piping
ghydra --json functions list | jq '.result[].name'

All commands support `--host`, `--port`, `--json`, and `--no-color` flags. See [GHYDRA_CLI.md](GHYDRA_CLI.md) for the full reference.

Timeout defaults are intentionally high for large binaries: - CLI/bridge HTTP timeout default: `900s` (`GHYDRA_TIMEOUT`) - Decompilation timeout default: `1200s` (`GHYDRA_DECOMP_TIMEOUT`) - Incomplete decompilation responses include retry guidance (`retry_recommended`, `suggested_timeout_seconds`)

MCP Clients

GhydraMCP works with any MCP-compatible client using **stdio transport**. It has been tested and confirmed working with:

- **Claude Desktop** - Anthropic's official desktop application - **Claude Code** - Anthropic's VS Code extension and CLI tool - **Cline** - Popular VS Code extension for AI-assisted coding

See the [Client Setup](#client-setup) section below for detailed configuration instructions for each client.

API Reference

Available Tools

Tools are grouped into namespaces:

**Instance Management** (`instances_*`): - `instances_list`: List active Ghidra instances (auto-discovers on default host) - **use this first** - `instances_discover`: Discover instances on a specific host (params: host [optional]) - **only use for non-default hosts** - `instances_register`: Register new instance (params: port, url [optional]) - `instances_unregister`: Remove instance (params: port) - `instances_use`: Set current working instance (params: port) - `instances_current`: Get current working instance info

**Function Analysis** (`functions_*`): - `functions_list`: List all functions (params: offset, limit, port [optional])

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 736 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
  2. [![GitHub release (latest by date)](https://img.shields.io/github/v/release/starsong-consulting/GhydraMCP)](https://github.com/starsong-consulting/GhydraMCP/releases)
  3. [![API Version](https://img.shields.io/badge/API-v3000-orange)](https://github.com/starsong-consulting/GhydraMCP/blob/main/GHIDRA_HTTP_API.md)
  4. [![GitHub stars](https://img.shields.io/github/stars/starsong-consulting/GhydraMCP)](https://github.com/starsong-consulting/GhydraMCP/stargazers)
  5. [![GitHub forks](https://img.shields.io/github/forks/starsong-consulting/GhydraMCP)](https://github.com/starsong-consulting/GhydraMCP/network/members)
  6. [![GitHub contributors](https://img.shields.io/github/contributors/starsong-consulting/GhydraMCP)](https://github.com/starsong-consulting/GhydraMCP/graphs/contributors)
  7. [![Build Status](https://github.com/starsong-consulting/GhydraMCP/actions/workflows/build.yml/badge.svg)](https://github.com/starsong-consulting/GhydraMCP/actions/workflows/build.yml)
  8. # GhydraMCP
  9. GhydraMCP connects [Ghidra](https://ghidra-sre.org/) to AI assistants for reverse engineering, over the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/mcp) or a command-line tool.
  10. ![GhydraMCP logo](https://github.com/user-attachments/assets/86b9b2de-767c-4ed5-b082-510b8109f00f)
  11. ## Overview
  12. > **Note:** The MCP bridge (`bridge_mcp_hydra.py`) is being deprecated in favor of the CLI tool (`ghydra`). The CLI provides the same capabilities with better output formatting, `--json` mode for scripting and AI tool use, and doesn't require an MCP-capable client. The bridge will continue to work but is no longer the recommended integration path.
  13. GhydraMCP has four components:
  14. 1. **Ghidra plugin**: exposes Ghidra over a HATEOAS REST API
  15. 2. **CLI tool (`ghydra`)**: a standalone terminal client; human-readable tables, plus `--json` for scripting and AI tool use
  16. 3. **MCP bridge** *(deprecated)*: a Python script that translates MCP requests into API calls
  17. 4. **Multiple instances**: connect several Ghidra windows to work on different binaries at once
  18. Through it, an assistant can:
  19. - Decompile and analyze binary code, with a few output formats
  20. - Map program structure, function relationships, and data types
  21. - Run binary analysis (cross-references, call graphs, data flow)
  22. - Edit the analysis (rename, annotate, create/delete/modify data)
  23. - Read and write memory
  24. - Follow HATEOAS links between resources
  25. GhydraMCP started as a fork of [GhidraMCP by Laurie Wired](https://github.com/LaurieWired/GhidraMCP/) and added multi-instance support, data manipulation, and a HATEOAS REST API.
  26. # Features
  27. ## Program analysis
  28. - **Decompilation**:
  29. - Convert binary functions to readable C code
  30. - Toggle between clean C-like pseudocode and raw decompiler output
  31. - Show/hide syntax trees for detailed analysis
  32. - Multiple simplification styles for different analysis approaches
  33. - **Static analysis**:
  34. - Cross-reference analysis (find callers and callees)
  35. - Call graph generation and traversal
  36. - Data flow analysis with variable tracking
  37. - Type propagation and reconstruction
  38. - Function relationship mapping
  39. - **Memory**:
  40. - Direct memory reading with hex and raw byte representation
  41. - Address space navigation and mapping
  42. - Memory segment analysis
  43. - **Symbols**:
  44. - View and analyze imports and exports
  45. - Identify library functions and dependencies
  46. - Symbol table exploration and manipulation
  47. - Namespace hierarchy visualization
  48. - Fully-qualified names: functions, symbols, data, variables, and xrefs are returned and matched by their namespace-qualified name (e.g. `MyClass::method`; global-namespace members are unprefixed). A bare name resolves in the global namespace only, and renaming with `::` moves a symbol into that namespace (created if absent)
  49. ## Interactive reverse engineering
  50. - **Code understanding**:
  51. - Explore function code in context
  52. - Analyze data structures and complex types
  53. - View disassembly with linking to decompiled code
  54. - Examine function prototypes and signatures
  55. - **Annotation**:
  56. - Rename functions, variables, and data
  57. - Add multiple comment types (EOL, plate, pre/post)
  58. - Create and modify data types
  59. - Set and update function signatures and prototypes
  60. ## Data manipulation
  61. - **Data**:
  62. - Create new data items with specified types
  63. - Delete existing data items
  64. - Rename data items
  65. - Set and update data types for existing items
  66. - Combined rename and retype operations
  67. - Type definition management
  68. - **Functions**:
  69. - Rename functions
  70. - Update function signatures with parameter information
  71. - Modify local variable names and types
  72. - Set function return types
  73. ## Multiple instances and projects
  74. - **Instances**:
  75. - Run multiple Ghidra instances simultaneously on ports 8192-8447 (256 port range)
  76. - Analyze different binaries in parallel
  77. - Connect to specific instances using port numbers
  78. - Auto-discovery of running Ghidra instances
  79. - Instance metadata with project and file information
  80. - Plugin version and API checking for compatibility
  81. - **Projects**:
  82. - Get current project information (name, location, file counts)
  83. - List all files in a project with filtering
  84. - Open project files in new CodeBrowser windows
  85. - Navigate project folder hierarchy
  86. - Automatic instance registration when opening new programs
  87. ## Navigation and discovery
  88. - List and search functions, classes, and namespaces
  89. - View memory segments and layout
  90. - Search by name, pattern, or signature
  91. - Resource discovery through HATEOAS links
  92. - Pagination for handling large result sets
  93. - Filtering capabilities across all resources
  94. # Installation
  95. ## Prerequisites
  96. - [Ghidra](https://ghidra-sre.org) 11.x or 12.x. Releases ship a separate build per Ghidra version; the extension's `ghidraVersion` must match your Ghidra version exactly.
  97. - Java 21 (Temurin 21 recommended) for building the plugin
  98. - Python3
  99. - MCP [SDK](https://github.com/modelcontextprotocol/python-sdk)
  100. ## Ghidra
  101. First, download the latest [release](https://github.com/starsong-consulting/GhydraMCP/releases) from this repository. The "Complete" artifact contains the zipped Ghidra plugin and the Python MCP bridge. Unpack the outer archive, then, add the plugin to Ghidra:
  102. 1. Run Ghidra
  103. 2. Select `File` -> `Install Extensions`
  104. 3. Click the `+` button
  105. 4. Select the `Ghydra-*-ghidra<version>.zip` that matches your Ghidra version (e.g. `...-ghidra12.1.2.zip` for Ghidra 12.1.2)
  106. 5. Restart Ghidra
  107. 6. Make sure the Ghydra plugin is enabled in `File` -> `Configure` -> `Developer`
  108. > **Note:** By default, the first CodeBrowser opened in Ghidra gets port 8192, the second gets 8193, and so on. You can check which ports are being used by looking at the Console in the Ghidra main (project) window - click the computer icon in the bottom right to "Open Console". Look for log entries like:
  109. > ```
  110. > (GhydraPlugin) GhydraMCP loaded on port 8193
  111. > (GhydraServer) GhydraMCP HTTP server started on port 8193
  112. > ```
  113. >
  114. > GhydraMCP now includes auto-discovery of running Ghidra instances, so manually registering each instance is typically not necessary. The MCP bridge will automatically discover and register instances on startup and periodically check for new ones.
  115. Video Installation Guide:
  116. https://github.com/user-attachments/assets/75f0c176-6da1-48dc-ad96-c182eb4648c3
  117. ## CLI Tool
  118. GhydraMCP includes `ghydra`, a command-line tool for interacting with Ghidra directly from the terminal. It works standalone, no MCP client needed.
  119. ```bash
  120. # Install
  121. pip install -e .
  122. # List running Ghidra instances
  123. ghydra instances list
  124. # Decompile a function
  125. ghydra functions decompile --name main
  126. # List strings matching a pattern
  127. ghydra data list-strings --filter "password"
  128. # Read memory as hex dump
  129. ghydra memory read --address 0x401000 --length 64
  130. # JSON output for scripting and piping
  131. ghydra --json functions list | jq '.result[].name'
  132. ```
  133. All commands support `--host`, `--port`, `--json`, and `--no-color` flags. See [GHYDRA_CLI.md](GHYDRA_CLI.md) for the full reference.
  134. Timeout defaults are intentionally high for large binaries:
  135. - CLI/bridge HTTP timeout default: `900s` (`GHYDRA_TIMEOUT`)
  136. - Decompilation timeout default: `1200s` (`GHYDRA_DECOMP_TIMEOUT`)
  137. - Incomplete decompilation responses include retry guidance (`retry_recommended`, `suggested_timeout_seconds`)
  138. ## MCP Clients
  139. GhydraMCP works with any MCP-compatible client using **stdio transport**. It has been tested and confirmed working with:
  140. - **Claude Desktop** - Anthropic's official desktop application
  141. - **Claude Code** - Anthropic's VS Code extension and CLI tool
  142. - **Cline** - Popular VS Code extension for AI-assisted coding
  143. See the [Client Setup](#client-setup) section below for detailed configuration instructions for each client.
  144. ## API Reference
  145. ### Available Tools
  146. Tools are grouped into namespaces:
  147. **Instance Management** (`instances_*`):
  148. - `instances_list`: List active Ghidra instances (auto-discovers on default host) - **use this first**
  149. - `instances_discover`: Discover instances on a specific host (params: host [optional]) - **only use for non-default hosts**
  150. - `instances_register`: Register new instance (params: port, url [optional])
  151. - `instances_unregister`: Remove instance (params: port)
  152. - `instances_use`: Set current working instance (params: port)
  153. - `instances_current`: Get current working instance info
  154. **Function Analysis** (`functions_*`):
  155. - `functions_list`: List all functions (params: offset, limit, port [optional])
  156. - `functions_get`: Get function details (params: name or address, port [optional]); `name` is the fully-qualified name (e.g. `MyClass::method`), a bare name resolves in the global namespace only
  157. - `functions_decompile`: Get decompiled C code (params: name or address, syntax_tree, style, timeout, port [optional]); incomplete results return retry metadata and suggested timeout
  158. - `functions_disassemble`: Get disassembled instructions (params: name or address, port [optional])
  159. - `functions_create`: Create function at address (params: address, port [optional])
  160. - `functions_rename`: Rename a function (params: old_name or address, new_name, port [optional]); a `new_name` containing `::` moves the function into that namespace (created if absent), a leading `::` moves it to the global namespace
  161. - `functions_set_signature`: Update function prototype (params: name or address, signature, port [optional])
  162. - `functions_delete`: Delete a function (params: name or address, port [optional])
  163. - `functions_get_variables`: Get function variables (params: name or address, port [optional])
  164. - `functions_update_variable`: Update a function variable (params: address, variable_name, new_name [optional], new_data_type [optional], port [optional])
  165. - `functions_set_comment`: Set function comment (params: address, comment, port [optional])
  166. **Data Manipulation** (`data_*`):
  167. - `data_list`: List data items (params: offset, limit, addr, name, name_contains, port [optional]); address lookups return defined data first, then label symbols if no defined data exists
  168. - `data_list_strings`: List all defined strings (params: offset, limit, filter, port [optional])
  169. - `data_create`: Create data at address (params: address, data_type, size [optional], port [optional])
  170. - `data_rename`: Rename data item (params: address, name, port [optional]); auto-defines a byte at the address if data is undefined
  171. - `data_delete`: Delete data item (params: address, port [optional])
  172. - `data_set_type`: Change data type (params: address, data_type, port [optional]); supports array syntax (e.g. `uint64_t[8]`) and auto-defines data when undefined
  173. **Struct Management** (`structs_*`):
  174. - `structs_list`: List all struct data types (params: offset, limit, category [optional], port [optional])
  175. - `structs_get`: Get detailed struct information (params: name, port [optional])
  176. - `structs_create`: Create new struct (params: name, category [optional], size [optional], description [optional], port [optional])
  177. - `structs_add_field`: Add field to struct (params: struct_name, field_name, field_type, offset [optional], comment [optional], port [optional])
  178. - `structs_update_field`: Update struct field (params: struct_name, field_name or field_offset, new_name [optional], new_type [optional], new_comment [optional], port [optional])
  179. - `structs_delete`: Delete struct (params: name, port [optional])
  180. **Memory Operations** (`memory_*`):
  181. - `memory_read`: Read bytes from memory (params: address, length, format, port [optional]); overlay-aware (`runtime::145e29b10` and plain offsets that map to overlays)
  182. - `memory_write`: Write bytes to memory (params: address, bytes_data, format, port [optional])
  183. **Cross-References** (`xrefs_*`):
  184. - `xrefs_list`: List cross-references (params: to_addr [optional], from_addr [optional], type [optional], offset, limit, port [optional])
  185. **Analysis** (`analysis_*`):
  186. - `analysis_run`: Trigger program analysis (params: analysis_options [optional], background [optional], port [optional])
  187. - `analysis_status`: Check analysis status (params: port [optional])
  188. - `analysis_get_callgraph`: Get function call graph (params: name or address, max_depth, port [optional])
  189. - `analysis_get_dataflow`: Perform reference-flow traversal from an address (params: address, direction, max_steps, port [optional])
  190. **Project Management** (`project_*`):
  191. - `project_info`: Get current project information (params: port [optional])
  192. - `project_list_files`: List files in project (params: folder, recursive, offset, limit, port [optional])
  193. - `project_open_file`: Open project file in CodeBrowser (params: path, port [optional])
  194. - `projects_list`: List projects (params: port [optional])
  195. - `projects_get`: Get project details by name (params: name, port [optional])
  196. - `programs_list`: List programs (params: project [optional], offset, limit, port [optional])
  197. - `programs_get`: Get program by ID or `current` (params: program_id [optional], port [optional])
  198. - `programs_delete`: Delete/close program by ID or `current` (params: program_id [optional], port [optional])
  199. > `programs_delete` and program import routes are currently exposed but may return `NOT_IMPLEMENTED` depending on plugin-side support.
  200. **Datatype Management** (`datatypes_*`):
  201. - `datatypes_list`: List data types (params: offset, limit, category [optional], kind [optional], port [optional])
  202. - `datatypes_search`: Search data types by name (params: name, offset, limit, port [optional])
  203. - `datatypes_create_struct`: Create struct datatype (params: name, category [optional], fields_json [optional], port [optional]); supports JSON field definitions
  204. - `datatypes_create_enum`: Create enum datatype (params: name, size [optional], category [optional], values_json [optional], port [optional]); supports JSON value definitions
  205. - `datatypes_create_union`: Create union datatype (params: name, category [optional], fields_json [optional], port [optional]); supports JSON field definitions
  206. **Comment Management** (`comments_*`):
  207. - `comments_set`: Set memory comment (params: address, comment [optional], comment_type [optional], port [optional])
  208. - `comments_get`: Get memory comment (params: address, comment_type [optional], port [optional])
  209. **UI Helpers** (`ui_*`):
  210. - `ui_get_current_address`: Get currently selected UI address (params: port [optional])
  211. - `ui_get_current_function`: Get currently selected UI function (params: port [optional])
  212. **Program Metadata** (`classes_*`, `symbols_*`, `segments_*`, `namespaces_*`, `variables_*`):
  213. - `classes_list`: List classes/namespaces (params: offset, limit, port [optional])
  214. - `symbols_list` / `symbols_imports` / `symbols_exports`: Enumerate symbols (params: offset, limit, port [optional])
  215. - `segments_list`: List memory blocks (params: offset, limit, name [optional], port [optional])
  216. - `namespaces_list`: List namespaces (params: offset, limit, port [optional])
  217. - `variables_list`: List variables (params: offset, limit, search [optional], global_only [optional], port [optional])
  218. **Example Usage**:
  219. ```python
  220. # Instance Management - Always start here
  221. client.use_tool("ghydra", "instances_list") # Auto-discovers instances on localhost
  222. client.use_tool("ghydra", "instances_use", {"port": 8192}) # Set working instance
  223. client.use_tool("ghydra", "instances_current") # Check current instance
  224. # Function Analysis
  225. client.use_tool("ghydra", "functions_list", {"offset": 0, "limit": 100})
  226. client.use_tool("ghydra", "functions_get", {"name": "main"})
  227. client.use_tool("ghydra", "functions_decompile", {"address": "0x00401000"})
  228. client.use_tool("ghydra", "functions_disassemble", {"name": "main"})
  229. client.use_tool("ghydra", "functions_rename", {"address": "0x00401000", "new_name": "process_data"})
  230. client.use_tool("ghydra", "functions_set_signature", {"address": "0x00401000", "signature": "int process_data(char* buf, int len)"})
  231. client.use_tool("ghydra", "functions_set_comment", {"address": "0x00401000", "comment": "Main processing function"})
  232. # Data Manipulation
  233. client.use_tool("ghydra", "data_list_strings", {"filter": "password"}) # Find strings containing "password"
  234. client.use_tool("ghydra", "data_list", {"offset": 0, "limit": 50})
  235. client.use_tool("ghydra", "data_create", {"address": "0x00401234", "data_type": "int"})
  236. client.use_tool("ghydra", "data_rename", {"address": "0x00401234", "name": "counter"})
  237. client.use_tool("ghydra", "data_set_type", {"address": "0x00401238", "data_type": "uint64_t[8]"})
  238. client.use_tool("ghydra", "data_delete", {"address": "0x0040123C"})
  239. # Struct Management
  240. client.use_tool("ghydra", "structs_create", {"name": "NetworkPacket", "category": "/network"})
  241. client.use_tool("ghydra", "structs_add_field", {
  242. "struct_name": "NetworkPacket",
  243. "field_name": "header",
  244. "field_type": "dword",
  245. "comment": "Packet header"
  246. })
  247. client.use_tool("ghydra", "structs_add_field", {
  248. "struct_name": "NetworkPacket",
  249. "field_name": "data_ptr",
  250. "field_type": "pointer"
  251. })
  252. client.use_tool("ghydra", "structs_update_field", {
  253. "struct_name": "NetworkPacket",
  254. "field_name": "header",
  255. "new_name": "packet_header",
  256. "new_comment": "Updated header field"
  257. })
  258. client.use_tool("ghydra", "structs_get", {"name": "NetworkPacket"})
  259. client.use_tool("ghydra", "structs_list", {"category": "/network"})
  260. # Memory Operations
  261. client.use_tool("ghydra", "memory_read", {"address": "runtime::145e29b10", "length": 16, "format": "hex"})
  262. client.use_tool("ghydra", "memory_write", {"address": "0x00401000", "bytes_data": "90909090", "format": "hex"})
  263. # Cross-References
  264. client.use_tool("ghydra", "xrefs_list", {"to_addr": "0x00401000"}) # Find callers
  265. client.use_tool("ghydra", "xrefs_list", {"from_addr": "0x00401000"}) # Find callees
  266. # Analysis
  267. client.use_tool("ghydra", "analysis_status") # Check if analysis is running
  268. client.use_tool("ghydra", "analysis_run", {"background": True}) # Trigger analysis in background
  269. client.use_tool("ghydra", "analysis_get_callgraph", {"name": "main", "max_depth": 5})
  270. client.use_tool("ghydra", "analysis_get_dataflow", {"address": "0x00401050", "direction": "forward"})
  271. # Project Management
  272. client.use_tool("ghydra", "project_info") # Get current project info
  273. client.use_tool("ghydra", "project_list_files", {"folder": "/", "recursive": True})
  274. client.use_tool("ghydra", "project_open_file", {"path": "/malware_samples/sample2.exe"})
  275. ```
  276. ## Client Setup
  277. GhydraMCP works with any MCP-compatible client. Below are configuration examples for popular AI coding assistants.
  278. ### Installation Methods
  279. #### Recommended: Local Installation from Release
  280. Download the latest [release](https://github.com/starsong-consulting/GhydraMCP/releases) to ensure the bridge and plugin versions are in sync.
  281. ```json
  282. {
  283. "mcpServers": {
  284. "ghydra": {
  285. "command": "uv",
  286. "args": [
  287. "run",
  288. "/ABSOLUTE_PATH_TO/bridge_mcp_hydra.py"
  289. ],
  290. "env": {
  291. "GHIDRA_HYDRA_HOST": "localhost"
  292. }
  293. }
  294. }
  295. }
  296. ```
  297. Replace `/ABSOLUTE_PATH_TO/` with the actual path to your `bridge_mcp_hydra.py` file.
  298. > **Note:** You can also use `python` instead of `uv run`, but then you'll need to manually install the requirements first with `pip install mcp requests`.
  299. #### Alternative: Direct from Repository with uvx
  300. If you want to use the latest development version, you can run directly from the GitHub repository:
  301. ```json
  302. {
  303. "mcpServers": {
  304. "ghydra": {
  305. "command": "uvx",
  306. "args": [
  307. "--from",
  308. "git+https://github.com/starsong-consulting/GhydraMCP",
  309. "ghydramcp"
  310. ],
  311. "env": {
  312. "GHIDRA_HYDRA_HOST": "localhost"
  313. }
  314. }
  315. }
  316. }
  317. ```
  318. > **Warning:** This method may pull a bridge version that's out of sync with your installed plugin. Only use this if you're tracking the latest development branch.
  319. ### Claude Desktop Configuration
  320. Add your chosen configuration method to your Claude Desktop configuration file:
  321. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  322. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  323. ### Claude Code Configuration
  324. Claude Code automatically discovers MCP servers configured in Claude Desktop. If you've set up the configuration above, Claude Code will have access to GhydraMCP tools immediately.
  325. Alternatively, you can configure Claude Code separately by adding the same configuration to the MCP settings in Claude Code's configuration.
  326. ### Cline Configuration
  327. Cline (VS Code extension) uses a separate configuration file. To set up GhydraMCP with Cline:
  328. 1. Open VS Code with Cline installed
  329. 2. Click the "MCP Servers" icon in Cline's interface
  330. 3. Select the "Configure" tab
  331. 4. Click "Configure MCP Servers" to edit `cline_mcp_settings.json`
  332. 5. Add the following configuration:
  333. ```json
  334. {
  335. "mcpServers": {
  336. "ghydra": {
  337. "command": "uv",
  338. "args": [
  339. "run",
  340. "/ABSOLUTE_PATH_TO/bridge_mcp_hydra.py"
  341. ],
  342. "env": {
  343. "GHIDRA_HYDRA_HOST": "localhost"
  344. },
  345. "disabled": false
  346. }
  347. }
  348. }
  349. ```
  350. If you prefer to use `python` directly instead of `uv`:
  351. ```json
  352. {
  353. "mcpServers": {
  354. "ghydra": {
  355. "command": "python",
  356. "args": [
  357. "/ABSOLUTE_PATH_TO/bridge_mcp_hydra.py"
  358. ],
  359. "env": {
  360. "GHIDRA_HYDRA_HOST": "localhost"
  361. },
  362. "disabled": false
  363. }
  364. }
  365. }
  366. ```
  367. > **Important:** Replace `/ABSOLUTE_PATH_TO/` with the actual absolute path to your `bridge_mcp_hydra.py` file. For example:
  368. > - **Linux/macOS**: `/home/username/GhydraMCP/bridge_mcp_hydra.py`
  369. > - **Windows**: `C:\\Users\\username\\GhydraMCP\\bridge_mcp_hydra.py`
  370. After saving the configuration, restart Cline to load the GhydraMCP server.
  371. ### 5ire Configuration
  372. 1. Tool Key: ghydra
  373. 2. Name: GhydraMCP
  374. 3. Command: `uv run /ABSOLUTE_PATH_TO/bridge_mcp_hydra.py`
  375. ## Example Session
  376. An example of an AI assistant driving Ghidra through GhydraMCP:
  377. **User:**
  378. ```
  379. Analyze the main function in the binary and identify any data structures being used.
  380. ```
  381. **Assistant:**
  382. ```
  383. I'll analyze the binary for you. Let me start by checking available Ghidra instances.
  384. [Uses instances_list]
  385. Found Ghidra instance on port 8192 analyzing "malware_sample.exe".
  386. [Uses instances_use with port 8192]
  387. Set instance 8192 as current working instance.
  388. [Uses functions_decompile with name "main"]
  389. Here's the decompiled main function:
  390. void main(void) {
  391. NetworkPacket *packet;
  392. int status;
  393. packet = (NetworkPacket *)malloc(0x20);
  394. packet->header = 0x1234;
  395. packet->data_ptr = allocate_buffer(0x100);
  396. status = process_packet(packet);
  397. ...
  398. }
  399. I can see this code uses a "NetworkPacket" structure. Let me check if it's already defined.
  400. [Uses structs_get with name "NetworkPacket"]
  401. The struct doesn't exist yet. Let me create it based on the decompiled code.
  402. [Uses structs_create with name "NetworkPacket", category "/network"]
  403. Created NetworkPacket struct.
  404. [Uses structs_add_field for each field]
  405. Added fields:
  406. - header (dword at offset 0)
  407. - data_ptr (pointer at offset 4)
  408. - size (dword at offset 8)
  409. - status (dword at offset 12)
  410. [Uses data_list_strings with filter "Error"]
  411. I also found several error strings that suggest this binary handles network communications with error checking.
  412. The main function appears to be the entry point for a network packet processing routine that allocates and processes data structures for network communication.
  413. ```
  414. **User:**
  415. ```
  416. What other binaries are in this project? Can you open one and compare its structure to this one?
  417. ```
  418. **Assistant:**
  419. ```
  420. Let me check what other files are in the current project.
  421. [Uses project_info]
  422. Current project: "MalwareAnalysis" at /home/user/ghidra_projects/MalwareAnalysis
  423. Contains 15 files across 3 folders.
  424. [Uses project_list_files with folder "/" and recursive True]
  425. Found these binaries in the project:
  426. - /malware_samples/sample1.exe (currently open)
  427. - /malware_samples/sample2.exe
  428. - /malware_samples/sample3.dll
  429. - /clean_samples/notepad.exe
  430. Let me open sample2.exe for comparison.
  431. [Uses project_open_file with path "/malware_samples/sample2.exe"]
  432. Opened sample2.exe in a new CodeBrowser window.
  433. [Uses instances_discover]
  434. Found new instance on port 8193 analyzing sample2.exe.
  435. [Uses instances_use with port 8193]
  436. Switched to the new instance.
  437. [Uses functions_list on port 8193]
  438. sample2.exe has a similar structure with 342 functions. Let me compare the main functions...
  439. ```
  440. **User:**
  441. ```
  442. Can you trace where process_packet is called from and show me the call graph?
  443. ```
  444. **Assistant:**
  445. ```
  446. I'll trace the call relationships for process_packet.
  447. [Uses xrefs_list with to_addr for process_packet]
  448. Found 3 callers of process_packet:
  449. - main at 0x401000
  450. - worker_thread at 0x401200
  451. - handle_request at 0x401450
  452. [Uses analysis_get_callgraph with name "process_packet", max_depth 3]
  453. Here's the call graph starting from process_packet:
  454. process_packet (0x401100)
  455. ├── validate_header (0x401150)
  456. │ └── check_magic (0x401180)
  457. ├── parse_data (0x4011A0)
  458. │ ├── extract_field (0x4011D0)
  459. │ └── validate_checksum (0x4011E0)
  460. └── send_response (0x401220)
  461. └── network_send (0x401250)
  462. This shows process_packet coordinates validation, parsing, and response transmission.
  463. ```
  464. # JSON Communication
  465. GhydraMCP uses JSON for all communication between the bridge or CLI and the Java plugin.
  466. ## API Architecture
  467. The REST API is HATEOAS-driven:
  468. ### Core API Design
  469. - **HATEOAS Architecture**: Each response includes navigational links for resource discovery
  470. - **Versioned Endpoints**: All requests verified against API version for compatibility
  471. - **Structured Responses**: Standardized JSON format with consistent field naming
  472. - **Proper HTTP Methods**: GET for retrieval, POST for creation, PATCH for updates, DELETE for removal
  473. - **Appropriate Status Codes**: Uses standard HTTP status codes for clear error handling
  474. ### Response Format
  475. All responses follow this HATEOAS-driven format:
  476. ```json
  477. {
  478. "id": "req-123",
  479. "instance": "http://localhost:8192",
  480. "success": true,
  481. "result": "...",
  482. "timestamp": 1712159482123,
  483. "_links": {
  484. "self": {"href": "/endpoint/current"},
  485. "related": [
  486. {"href": "/endpoint/related1", "name": "Related Resource 1"},
  487. {"href": "/endpoint/related2", "name": "Related Resource 2"}
  488. ]
  489. }
  490. }
  491. ```
  492. For list responses, pagination information is included:
  493. ```json
  494. {
  495. "id": "req-123",
  496. "instance": "http://localhost:8192",
  497. "success": true,
  498. "result": [ ... objects ... ],
  499. "size": 150,
  500. "offset": 0,
  501. "limit": 50,
  502. "_links": {
  503. "self": { "href": "/functions?offset=0&limit=50" },
  504. "next": { "href": "/functions?offset=50&limit=50" },
  505. "prev": { "href": "/functions?offset=0&limit=50" }
  506. }
  507. }
  508. ```
  509. Error responses include detailed information:
  510. ```json
  511. {
  512. "id": "req-123",
  513. "instance": "http://localhost:8192",
  514. "success": false,
  515. "error": {
  516. "code": "RESOURCE_NOT_FOUND",
  517. "message": "Function 'main' not found in current program"
  518. },
  519. "status_code": 404,
  520. "timestamp": 1712159482123,
  521. "_links": {
  522. "self": {"href": "/functions/main"}
  523. }
  524. }
  525. ```
  526. The links let a client discover related resources without hardcoding URLs.
  527. # Testing
  528. GhydraMCP has test suites for the HTTP API and the MCP bridge. See [TESTING.md](TESTING.md) for how to run them.
  529. ## HTTP API Tests
  530. Tests the HTTP endpoints exposed by the Java plugin:
  531. - Response format and structure
  532. - JSON structure consistency
  533. - Required fields in responses
  534. - Error handling
  535. ## MCP Bridge Tests
  536. Tests the MCP bridge functionality:
  537. - MCP protocol communication
  538. - Tool availability and structure
  539. - Response format and structure
  540. - JSON structure consistency
  541. # Building from Source
  542. You can build different artifacts with Maven. The build needs the Ghidra module
  543. jars: either set `GHIDRA_HOME` to your Ghidra install (recommended), or place the
  544. jars in `lib/`.
  545. ```
  546. # Build against a specific Ghidra install (recommended). Works for 11.x or 12.x.
  547. # -Dghidra.version stamps the extension's ghidraVersion (must match the install).
  548. GHIDRA_HOME=/path/to/ghidra_12.1.2_PUBLIC mvn clean package -Dghidra.version=12.1.2
  549. ```
  550. CI builds a matrix over the latest Ghidra 11.x and 12.x and attaches a per-version
  551. plugin zip to each release.
  552. ## Build Everything (Default)
  553. Build both the Ghidra plugin and the complete package:
  554. ```
  555. mvn clean package
  556. ```
  557. This creates:
  558. - `target/Ghydra-[version].zip` - The Ghidra plugin only
  559. - `target/Ghydra-Complete-[version].zip` - Complete package with plugin and bridge script
  560. Install the plugin zip via Ghidra's `File` -> `Install Extensions` (first time);
  561. for later updates you can swap `lib/Ghydra.jar` in the installed extension and
  562. restart Ghidra.
  563. ## Build Ghidra Plugin Only
  564. If you only need the Ghidra plugin:
  565. ```
  566. mvn clean package -P plugin-only
  567. ```
  568. ## Build Complete Package Only
  569. If you only need the combined package:
  570. ```
  571. mvn clean package -P complete-only
  572. ```
  573. The Ghidra plugin includes these files required for Ghidra to recognize the extension:
  574. - lib/Ghydra.jar
  575. - extension.properties
  576. - Module.manifest

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.