Skip to content
Back to search

GhidraMCP

Active Socket based MCP Server for Ghidra

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/13bm--ghidramcp/badge.svg)](/listings/13bm--ghidramcp)

HTML

<a href="/listings/13bm--ghidramcp"><img src="/api/listings/13bm--ghidramcp/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/) 12.0.3+ - Java 21+ - An MCP-compatible AI client ([Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), etc.)

Install

1. Download the latest release ZIP from [Releases](https://github.com/13bm/GhidraMCP/releases) 2. In Ghidra: **File > Install Extensions > "+" > select the ZIP** 3. Restart Ghidra

Enable

1. Open a project and a program (binary) 2. **File > Configure > GhidraMCP -- check MCPServerPlugin** 3. The plugin auto-starts the TCP server (default `localhost:8765`) and launches the bridge

To configure Claude Desktop, open **MCP > Settings** and click **Write to Claude Config**. For other MCP clients, click **Copy to Clipboard** and add this to your client config:

{
  "mcpServers": {
    "ghidra": {
      "command": "/path/to/mcp_bridge",
      "args": ["--host", "localhost", "--port", "8765"]
    }
  }
}

If you have an API key set, include it in the `env` block (the plugin does this automatically):

{
  "mcpServers": {
    "ghidra": {
      "command": "/path/to/mcp_bridge",
      "args": ["--host", "localhost", "--port", "8765"],
      "env": {
        "GHIDRA_API_KEY": "your-key-here"
      }
    }
  }
}

You can also grab the snippet from Ghidra: **MCP > Copy MCP Config** (copies it to your clipboard).

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 · 361 lines

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

  1. # GhidraMCP
  2. [![Build](https://github.com/13bm/GhidraMCP/actions/workflows/build.yml/badge.svg)](https://github.com/13bm/GhidraMCP/actions/workflows/build.yml)
  3. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  4. A Ghidra extension that exposes 70 reverse-engineering tools to AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Open a binary in Ghidra, enable the plugin, and let Claude (or any MCP client) decompile functions, rename symbols, annotate code, search for vulnerabilities, and more.
  5. ## Architecture
  6. ```
  7. AI Client (Claude Desktop / CLI)
  8. | stdio + MCP JSON-RPC
  9. v
  10. Go MCP Bridge (mcp_bridge)
  11. | TCP, length-prefixed JSON-RPC
  12. v
  13. Ghidra Plugin (MCPServerPlugin)
  14. |
  15. v
  16. Ghidra Program API
  17. ```
  18. The **Ghidra plugin** (Java) starts a TCP server inside Ghidra and auto-launches the **Go bridge** binary. The bridge speaks MCP over stdio to the AI client and forwards calls to the Java plugin over a local TCP socket with 4-byte length-prefixed JSON-RPC framing. Optional API-key authentication protects the TCP channel.
  19. ## Features
  20. - **70 MCP tools** spanning query, mutation, analysis, malware triage, IoT/embedded security, structure management, async decompilation, and multi-instance support
  21. - **Easy setup** -- plugin auto-starts the bridge; use **MCP > Settings > Write to Claude Config** to configure your MCP client
  22. - **Cross-platform** -- prebuilt bridge binaries for Linux x86_64, Windows x86_64, macOS x86_64 and macOS ARM64
  23. - **Configurable** -- port, localhost-only binding, API-key auth, auto-start, bridge enable/disable via `GhidraMCP.properties`
  24. - **Multi-instance** -- work with multiple Ghidra windows simultaneously using `target_port` to route tool calls
  25. - **Async decompilation** -- decompile large functions without blocking; poll for results later
  26. - **Connection retry** -- the bridge reconnects automatically if Ghidra restarts or the connection drops
  27. - **Pagination** -- large result sets (functions, strings, imports, ...) support `offset`/`limit` for safe incremental retrieval
  28. - **CI/CD** -- automated builds, Go + Java tests, Ghidra integration tests, and auto-release when a new Ghidra version drops
  29. ## Quick Start
  30. ### Prerequisites
  31. - [Ghidra](https://ghidra-sre.org/) 12.0.3+
  32. - Java 21+
  33. - An MCP-compatible AI client ([Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), etc.)
  34. ### Install
  35. 1. Download the latest release ZIP from [Releases](https://github.com/13bm/GhidraMCP/releases)
  36. 2. In Ghidra: **File > Install Extensions > "+" > select the ZIP**
  37. 3. Restart Ghidra
  38. ### Enable
  39. 1. Open a project and a program (binary)
  40. 2. **File > Configure > GhidraMCP -- check MCPServerPlugin**
  41. 3. The plugin auto-starts the TCP server (default `localhost:8765`) and launches the bridge
  42. To configure Claude Desktop, open **MCP > Settings** and click **Write to Claude Config**. For other MCP clients, click **Copy to Clipboard** and add this to your client config:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "ghidra": {
  47. "command": "/path/to/mcp_bridge",
  48. "args": ["--host", "localhost", "--port", "8765"]
  49. }
  50. }
  51. }
  52. ```
  53. If you have an API key set, include it in the `env` block (the plugin does this automatically):
  54. ```json
  55. {
  56. "mcpServers": {
  57. "ghidra": {
  58. "command": "/path/to/mcp_bridge",
  59. "args": ["--host", "localhost", "--port", "8765"],
  60. "env": {
  61. "GHIDRA_API_KEY": "your-key-here"
  62. }
  63. }
  64. }
  65. }
  66. ```
  67. You can also grab the snippet from Ghidra: **MCP > Copy MCP Config** (copies it to your clipboard).
  68. ## Tools
  69. > **Full reference with parameters, types, and examples:** **[TOOLS.md](TOOLS.md)**
  70. The tables below give a quick overview. See [TOOLS.md](TOOLS.md) for detailed parameter docs.
  71. ### Query (1-21)
  72. | Tool | Description |
  73. |------|-------------|
  74. | `list_functions` | List all functions with entry points, sizes, return types |
  75. | `list_classes` | List all classes / namespaces |
  76. | `list_imports` | List imported symbols and external dependencies |
  77. | `list_exports` | List exported symbols |
  78. | `list_namespaces` | List all namespaces |
  79. | `list_data_items` | List defined data (globals, constants, arrays, structs) |
  80. | `list_strings` | List strings with optional substring filter |
  81. | `search_functions_by_name` | Search functions by name substring |
  82. | `get_function_by_address` | Detailed info for a function at an address |
  83. | `get_current_address` | Address currently selected in Ghidra |
  84. | `get_current_function` | Function at the current cursor position |
  85. | `decompile_function` | Decompile by name to C pseudocode |
  86. | `decompile_function_by_address` | Decompile by address to C pseudocode |
  87. | `disassemble_function` | Raw disassembly listing for a function |
  88. | `get_xrefs_to` | Cross-references TO an address |
  89. | `get_xrefs_from` | Cross-references FROM an address |
  90. | `get_function_xrefs` | All xrefs (callers + callees) for a function |
  91. | `get_program_info` | Program metadata (arch, compiler, format, etc.) |
  92. | `get_memory_map` | Memory layout with segment permissions |
  93. | `get_variables` | Parameters and locals for a function |
  94. ### Mutation (22-38)
  95. | Tool | Description |
  96. |------|-------------|
  97. | `rename_function` | Rename a function by name |
  98. | `rename_function_by_address` | Rename a function by address |
  99. | `rename_data` | Rename a data label |
  100. | `rename_variable` | Rename a local variable |
  101. | `set_decompiler_comment` | Set a decompiler-view comment |
  102. | `set_disassembly_comment` | Set a disassembly-view comment |
  103. | `set_function_prototype` | Set full function prototype |
  104. | `set_local_variable_type` | Change a variable's data type |
  105. | `set_bookmark` | Add a bookmark |
  106. | `remove_bookmark` | Remove a bookmark |
  107. | `set_equate` | Set a named constant on a scalar operand |
  108. | `create_structure` | Create a structure data type |
  109. | `create_enum` | Create an enum data type |
  110. | `apply_data_type` | Apply a data type at an address |
  111. | `set_namespace` | Set namespace or class for a function |
  112. | `set_calling_convention` | Set calling convention for a function |
  113. | `set_image_base` | Set the image base address |
  114. | `set_memory_permissions` | Modify memory block permissions |
  115. ### Advanced Analysis (39-45)
  116. | Tool | Description |
  117. |------|-------------|
  118. | `patch_bytes` | Patch raw bytes at an address |
  119. | `get_basic_blocks` | Get basic blocks for a function |
  120. | `extract_api_call_sequences` | Extract API call sequences for security analysis |
  121. | `identify_user_input_sources` | Find user-input entry points |
  122. | `generate_call_graph` | Hierarchical call graph |
  123. | `identify_crypto_patterns` | Detect crypto implementations |
  124. | `find_obfuscated_strings` | Locate obfuscated strings |
  125. ### Malware Analysis (46-53)
  126. | Tool | Description |
  127. |------|-------------|
  128. | `search_bytes` | Search for byte patterns |
  129. | `emulate_function` | Emulate a function |
  130. | `extract_iocs` | Extract indicators of compromise |
  131. | `find_dynamic_api_resolution` | Detect dynamic API resolution |
  132. | `detect_anti_analysis` | Detect anti-analysis techniques |
  133. | `add_external_function` | Add an external function reference |
  134. | `get_pe_info` | PE header details |
  135. | `get_elf_info` | ELF header details |
  136. ### IoT / Embedded Security (54-59)
  137. | Tool | Description |
  138. |------|-------------|
  139. | `create_memory_block` | Create a memory block |
  140. | `detect_security_mitigations` | Detect binary security mitigations |
  141. | `find_format_string_vulns` | Find format-string vulnerabilities |
  142. | `find_rop_gadgets` | Find ROP gadgets |
  143. | `detect_control_flow_flattening` | Detect control-flow flattening |
  144. | `mark_code_coverage` | Mark code coverage regions |
  145. ### Utility (60-62)
  146. | Tool | Description |
  147. |------|-------------|
  148. | `get_bookmarks` | List bookmarks (optionally by address) |
  149. | `list_equates` | List all equates |
  150. | `ping` | Health-check the connection |
  151. ### Multi-Instance (63)
  152. | Tool | Description |
  153. |------|-------------|
  154. | `list_ghidra_instances` | Scan ports 8765-8774 for running Ghidra instances |
  155. All tools accept an optional `target_port` parameter to route calls to a specific Ghidra instance. This lets you work with multiple binaries open in separate Ghidra windows simultaneously.
  156. ### Structure Management (64-68)
  157. | Tool | Description |
  158. |------|-------------|
  159. | `get_structure` | Get full details of a structure (fields, offsets, types) |
  160. | `list_structures` | List all defined structures with pagination |
  161. | `edit_structure` | Add, insert, delete, replace, or clear fields in a structure |
  162. | `rename_structure` | Rename an existing structure |
  163. | `delete_structure` | Delete a structure data type |
  164. ### Async Decompilation (69-70)
  165. | Tool | Description |
  166. |------|-------------|
  167. | `decompile_function_async` | Start async decompilation of a large function (returns task ID) |
  168. | `get_decompile_result` | Poll for an async decompilation result by task ID |
  169. Async decompilation is useful for large functions that may take 30+ seconds to decompile. The client can start the decompilation, continue other work, and poll for the result later.
  170. ## Configuration
  171. The plugin stores settings in `GhidraMCP.properties` inside Ghidra's user settings directory:
  172. | Property | Default | Description |
  173. |----------|---------|-------------|
  174. | `port` | `8765` | TCP port for the Java server |
  175. | `localhost_only` | `true` | Bind to localhost only |
  176. | `api_key` | *(empty)* | Shared secret for bridge authentication |
  177. | `auto_start` | `true` | Start the server when the plugin loads |
  178. | `bridge_enabled` | `true` | Auto-launch the Go bridge binary |
  179. ### Settings Dialog
  180. Open **MCP > Settings** in the Ghidra menu to configure all properties through a GUI. The dialog includes:
  181. - Editable fields for port, localhost binding, API key, auto-start, and bridge enabled
  182. - **Generate** button to create a cryptographically random 32-character API key
  183. - **Write to Claude Config** button to merge GhidraMCP into Claude Desktop's `claude_desktop_config.json`
  184. - **Copy to Clipboard** button to copy the MCP config JSON snippet for manual setup
  185. - Security warning if you enable remote access without an API key
  186. - Auto-restart prompt if the server is running when you save
  187. Changes are saved to disk when you click OK. You can also edit the properties file directly at the path shown in the dialog.
  188. If `auto_start` is `false`, start the server manually from **MCP > Toggle Server** in the Ghidra menu.
  189. > **Note:** The `bridge_enabled` setting is for advanced use cases — developers debugging the bridge binary or users with a custom MCP client that talks TCP directly to the Java server. Most users should leave it enabled.
  190. ## Security
  191. By default the TCP server binds to **localhost only** and has **no API key**, which is fine for local single-user use. For stricter setups:
  192. ### API-Key Authentication
  193. 1. Open **MCP > Settings** and click **Generate** to create a random key (or type your own)
  194. 2. Click OK to save — the bridge picks up the key automatically on next start
  195. 3. On connect, the bridge sends an `authenticate` request with the key before any other calls
  196. 4. The server rejects all non-auth requests until authentication succeeds
  197. 5. After **3 failed attempts** the server terminates the connection
  198. The API key is passed to the bridge via the `GHIDRA_API_KEY` environment variable (not as a CLI flag) to prevent leaking it in the process argument list. When running the bridge manually, set the environment variable:
  199. ```bash
  200. # Linux/macOS
  201. export GHIDRA_API_KEY="your-key-here"
  202. ./mcp_bridge --host localhost --port 8765
  203. # Windows (PowerShell)
  204. $env:GHIDRA_API_KEY = "your-key-here"
  205. .\mcp_bridge.exe --host localhost --port 8765
  206. ```
  207. When an API key is set, the **Write to Claude Config** and **Copy to Clipboard** buttons in the Settings dialog include the key in the `env` block automatically.
  208. ### Localhost Binding
  209. With `localhost_only=true` (default), the server only accepts connections from `127.0.0.1`. Set to `false` if you need remote access (e.g., Ghidra on a headless server), but **always use an API key** when exposing the port beyond localhost.
  210. ### Remote / Headless Setup
  211. GhidraMCP can serve AI clients running on a different machine. This is useful when Ghidra runs on a headless analysis server while the AI client runs elsewhere.
  212. 1. Open **MCP > Settings**
  213. 2. Uncheck **Localhost Only** to accept remote connections
  214. 3. Click **Generate** to create an API key (always use one for remote access)
  215. 4. Click OK and restart the server
  216. On the remote machine, configure the MCP client to point at the Ghidra host:
  217. ```json
  218. {
  219. "mcpServers": {
  220. "ghidra": {
  221. "command": "/path/to/mcp_bridge",
  222. "args": ["--host", "ghidra-server.local", "--port", "8765"],
  223. "env": {
  224. "GHIDRA_API_KEY": "your-key-here"
  225. }
  226. }
  227. }
  228. }
  229. ```
  230. > **Warning:** Always use an API key when exposing the server beyond localhost. Without authentication, anyone who can reach the port has full access to the Ghidra API.
  231. ## Building from Source
  232. ```bash
  233. git clone https://github.com/13bm/GhidraMCP.git
  234. cd GhidraMCP
  235. ```
  236. ### Build the Go bridge
  237. ```bash
  238. cd mcp-bridge
  239. go build -o mcp_bridge .
  240. cd ..
  241. ```
  242. ### Build the Ghidra extension
  243. ```bash
  244. export GHIDRA_INSTALL_DIR=/path/to/ghidra
  245. gradle buildExtension
  246. ```
  247. The extension ZIP will be in `dist/`.
  248. ### Run tests
  249. ```bash
  250. # Go tests
  251. cd mcp-bridge && go test ./... -v && cd ..
  252. # Java unit + integration tests (requires Xvfb on headless Linux)
  253. xvfb-run gradle test -PGHIDRA_INSTALL_DIR=$GHIDRA_INSTALL_DIR
  254. ```
  255. ## CI/CD
  256. The project uses GitHub Actions for automated builds and releases:
  257. - **`build.yml`** -- Triggered on push/PR to `master` and on tags. Runs Go tests, cross-compiles the bridge for 4 platforms, runs Java unit + Ghidra integration tests under Xvfb, builds the extension ZIP, and creates GitHub Releases on `v*` tags.
  258. - **`check-ghidra-release.yml`** -- Runs daily. Detects new Ghidra releases, opens a version-bump PR, auto-approves via GitHub App, and auto-merges if all tests pass.
  259. ## Contributing
  260. Contributions welcome! Please open issues or submit pull requests.
  261. 1. Fork the repository
  262. 2. Create a feature branch: `git checkout -b feature/my-feature`
  263. 3. Commit your changes
  264. 4. Push and open a Pull Request
  265. ## License
  266. [Apache License 2.0](LICENSE)
  267. ## Acknowledgments
  268. - [NSA / Ghidra](https://github.com/NationalSecurityAgency/ghidra)
  269. - [Model Context Protocol](https://modelcontextprotocol.io/)
  270. - [mcp-go](https://github.com/mark3labs/mcp-go) -- Go MCP SDK
  271. ---
  272. *GhidraMCP is not affiliated with or endorsed by the NSA or the Ghidra project.*

Ratings and comments

Sign in to rate this skill.

Sign in

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