ghidra-mcp-complete
MCP server giving AI assistants full access to Ghidra 12.2 (679 tools)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 20 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Alfa16bravo/ghidra-mcp-complete with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Alfa16bravo/ghidra-mcp-complete'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/alfa16bravo--ghidra-mcp-complete)HTML
<a href="/listings/alfa16bravo--ghidra-mcp-complete"><img src="/api/listings/alfa16bravo--ghidra-mcp-complete/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Get the sources
Clone the repository **inside your Ghidra installation folder** (simplest: the scripts then find Ghidra on their own):
cd C:\path\to\ghidra_12.2_PUBLIC git clone https://github.com/Alfa16bravo/ghidra-mcp-complete.git GhidraMCP
Anywhere else works too: set `GHIDRA_INSTALL_DIR` to your Ghidra folder (the one containing `ghidraRun.bat`), or pass `-GhidraDir` to the scripts.
2. Build and install the extension
Close Ghidra first (it locks the extension jar), then:
powershell -ExecutionPolicy Bypass -File GhidraMCP\build.ps1
This compiles the extension with `javac` (no Gradle needed), installs it into `<ghidra>\Ghidra\Extensions\GhidraMCP` and regenerates `bridge\tools.json`. Options: `-GhidraDir <path>`, `-Zip` (also create an installable `dist\ghidra_12.2_PUBLIC_<date>_GhidraMCP.zip`), `-NoInstall`.
**Alternative - release zip:** download the extension zip from the [Releases page](https://github.com/Alfa16bravo/ghidra-mcp-complete/releases), then in Ghidra use `File > Install Extensions > +`, pick the zip and restart Ghidra. You still need the repository (or at least the `bridge` folder and the `.bat` launchers) for the MCP client side.
3. Register the server in your MCP client
See [Connecting an MCP client](#connecting-an-mcp-client).
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 · 277 lines
- # GhidraMCP
- A [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants (Claude Code,
- Claude Desktop, and any other MCP client) full access to [Ghidra](https://github.com/NationalSecurityAgency/ghidra) **12.2**:
- **679 tools** covering the decompiler, listing, functions, symbols, data types, memory, scripting, p-code emulation,
- Version Tracking, Function ID, BSim, file systems and executable formats, the debugger and the Ghidra GUI itself.
- It runs **inside Ghidra** (a plugin of the CodeBrowser, so the assistant works on what you see and you watch its
- changes live) or **headless** (no GUI, started on demand by the assistant itself).
- > Every change made through the server is a normal Ghidra transaction: it can be undone with Ctrl+Z (or the `undo`
- > tool) and is saved only when you save the program.
- ## Contents
- - [What it can do](#what-it-can-do)
- - [How it works](#how-it-works)
- - [Requirements](#requirements)
- - [Installation](#installation)
- - [Starting Ghidra with the server](#starting-ghidra-with-the-server)
- - [Connecting an MCP client](#connecting-an-mcp-client)
- - [Using it](#using-it)
- - [Tools](#tools)
- - [Configuration](#configuration)
- - [Security](#security)
- - [Development](#development)
- - [Status and limitations](#status-and-limitations)
- - [License](#license)
- ## What it can do
- - **Read and understand code**: decompile (with C ↔ address mapping, AST tokens, alternate simplification styles),
- disassemble, p-code, control-flow graphs, call graphs, data-flow slices, call-site argument recovery, constant propagation.
- - **Annotate**: rename functions, variables, labels and namespaces; set prototypes and calling conventions; create and
- edit structs, unions, enums and typedefs (or parse C headers); comments, bookmarks, equates, colors - in bulk with `batch`.
- - **Run code without running the program**: stateful p-code emulation sessions - call a decryption or hashing routine
- with your own arguments (`emu_call`, even `main(argc, argv)`), breakpoints, hooks, snapshots, traces. Common libc and
- Win32 routines (stdio, memory, strings, anti-debug probes, ...) are emulated automatically.
- - **Triage malware and unknown binaries**: one-call triage report, capability detection by API usage, IOC extraction,
- anti-analysis and packer detection, crypto constants, stack strings, XOR brute force, API-hash resolution, YARA rule
- generation.
- - **Compare programs**: Version Tracking sessions and correlators, program diff and merge, function similarity, Function ID
- databases, BSim databases (local H2 files).
- - **Work with files**: probe and extract containers (zip, 7z, tar, ISO, ext4, firmware images, ...), import nested files,
- PE / ELF / Mach-O structure details, resources, certificates, patched-binary export.
- - **Import / export**: PDB and DWARF, symbol maps, IDA / x64dbg / radare2 scripts, SARIF, XML, C headers, Graphviz /
- GraphML / JSON graphs, Markdown reports.
- - **Drive Ghidra itself**: projects, version control, analyzers and options, scripts (run any Ghidra script, or arbitrary
- Java code with the full API through `run_script_inline`), the debugger (Trace RMI), and the GUI (navigation, selection,
- screenshots, any menu action, tables, options).
- ## How it works
- ```
- MCP client ──stdio──► bridge/ghidra_mcp_bridge.py ──HTTP 127.0.0.1:8765──► Ghidra
- (Claude Code, ...) (Python, no dependencies) ├─ GUI: GhidraMCPPlugin in the CodeBrowser
- └─ headless: ghidramcp.HeadlessMain
- ```
- - `src/ghidramcp/` - the Ghidra extension (Java): an HTTP server on 127.0.0.1 plus the tools, one `T_*.java` file per domain.
- - `bridge/ghidra_mcp_bridge.py` - the stdio MCP server the client launches. It finds running Ghidra instances
- (ports 8765-8774), can start a headless Ghidra by itself, and serves the tool list even when Ghidra is not running.
- - The extension also speaks MCP directly (Streamable HTTP) on `http://127.0.0.1:8765/mcp` for clients that support it.
- ## Requirements
- | | Version |
- |---|---|
- | Ghidra | **12.2** (PUBLIC release). Other versions are not supported: the extension is compiled against the exact Ghidra jars. |
- | JDK | 25 or newer (the one Ghidra 12.2 needs), with `javac` and `jar` - only to build. |
- | Python | 3.8 or newer for the bridge (standard library only). |
- | OS | Windows (the build and launch scripts are PowerShell / batch). |
- ## Installation
- ### 1. Get the sources
- Clone the repository **inside your Ghidra installation folder** (simplest: the scripts then find Ghidra on their own):
- ```bat
- cd C:\path\to\ghidra_12.2_PUBLIC
- git clone https://github.com/Alfa16bravo/ghidra-mcp-complete.git GhidraMCP
- ```
- Anywhere else works too: set `GHIDRA_INSTALL_DIR` to your Ghidra folder (the one containing `ghidraRun.bat`), or pass
- `-GhidraDir` to the scripts.
- ### 2. Build and install the extension
- Close Ghidra first (it locks the extension jar), then:
- ```powershell
- powershell -ExecutionPolicy Bypass -File GhidraMCP\build.ps1
- ```
- This compiles the extension with `javac` (no Gradle needed), installs it into `<ghidra>\Ghidra\Extensions\GhidraMCP`
- and regenerates `bridge\tools.json`. Options: `-GhidraDir <path>`, `-Zip` (also create an installable
- `dist\ghidra_12.2_PUBLIC_<date>_GhidraMCP.zip`), `-NoInstall`.
- **Alternative - release zip:** download the extension zip from the [Releases page](https://github.com/Alfa16bravo/ghidra-mcp-complete/releases), then in Ghidra use
- `File > Install Extensions > +`, pick the zip and restart Ghidra. You still need the repository (or at least the
- `bridge` folder and the `.bat` launchers) for the MCP client side.
- ### 3. Register the server in your MCP client
- See [Connecting an MCP client](#connecting-an-mcp-client).
- ## Starting Ghidra with the server
- ### GUI (recommended: the assistant works on what you see)
- Start Ghidra with **`GhidraMCP\ghidra-mcp-gui.bat`** instead of `ghidraRun.bat`. It starts the normal Ghidra and enables
- the plugin automatically in every CodeBrowser that opens. Open a program; the status bar shows
- `GhidraMCP server listening on 127.0.0.1:8765`.
- Manual alternative (once per tool): in the CodeBrowser, `File > Configure`, click `Configure` under *Miscellaneous*, tick
- **GhidraMCPPlugin**, then `File > Save Tool`. From then on `ghidraRun.bat` is enough.
- Several CodeBrowser windows each get their own port (8765, 8766, ...); the assistant picks one with `ghidra_instances` /
- `ghidra_connect`.
- ### Headless (no GUI)
- Nothing to do: when no Ghidra is running the assistant can call `ghidra_launch_headless` itself. Or start it by hand:
- ```bat
- GhidraMCP\ghidra-mcp-headless.bat --project-dir D:\re\projects --project-name work --import C:\samples\target.exe
- ```
- Options: `--project-dir` (default `%USERPROFILE%\ghidra_mcp_projects`), `--project-name` (default `mcp`, created if
- missing), `--port`, `--import FILE` (repeatable, imported and auto-analyzed), `--open /project/path` (repeatable).
- A project that is open in the Ghidra GUI is locked and cannot be opened headless at the same time.
- ## Connecting an MCP client
- The client launches the bridge with Python. Replace the path with yours.
- **Claude Code**
- ```bat
- claude mcp add --scope user ghidra -- python "C:\path\to\ghidra_12.2_PUBLIC\GhidraMCP\bridge\ghidra_mcp_bridge.py"
- ```
- **Claude Desktop** (`claude_desktop_config.json`) and most other clients (Cursor, VS Code, Windsurf, ...):
- ```json
- {
- "mcpServers": {
- "ghidra": {
- "command": "python",
- "args": ["C:\\path\\to\\ghidra_12.2_PUBLIC\\GhidraMCP\\bridge\\ghidra_mcp_bridge.py"]
- }
- }
- }
- ```
- **Direct HTTP** (clients that support Streamable HTTP, while Ghidra is running): `http://127.0.0.1:8765/mcp`.
- The bridge is still recommended: it handles discovery, several instances and headless start-up.
- With 679 tools, clients that support deferred / searchable tool loading (such as Claude Code) only load the schemas
- they need; inside the server, `search_tools`, `list_tool_groups` and `describe_tool` help find the right tool.
- ## Using it
- Just ask in natural language, for example:
- - *"What does the program open in Ghidra do? Give me a triage report and the most interesting functions."*
- - *"Decompile the function under my cursor, rename its variables and give it a proper prototype."*
- - *"Find the license check, explain the algorithm and emulate it to recover a valid key."*
- - *"List every call to CreateFileW with its decoded path argument."*
- - *"Create a struct from how param_1 is used in FUN_00401990 and apply it."*
- Conventions shared by the tools:
- - Addresses accept hex (`0x401000`, `401000h`), `space:offset`, or a symbol name.
- - Functions accept a name (`Class::method`) or any address inside the function.
- - Most tools take an optional `program` (name or project path) to target another open program.
- - List tools paginate with `offset` / `limit`; filters are case-insensitive substrings or regexes written `/like this/`.
- - `batch` runs many calls in one request; `run_script_inline` runs arbitrary Java (full Ghidra API) for anything else.
- - Changes are undoable (`undo` / `redo`); `save_program` persists them.
- ## Tools
- The full catalog with every tool, its description and parameters is in **[TOOLS.md](TOOLS.md)**.
- | Domain | Tools |
- |---|---:|
- | Bridge: instances, connection, headless start-up | 3 |
- | Program, project & analysis | 21 |
- | Project management, version control & multi-program operations | 45 |
- | Memory | 10 |
- | Advanced memory & search | 34 |
- | Listing & disassembly | 12 |
- | Functions | 14 |
- | Control flow, overrides, externals & analysis control | 54 |
- | Decompiler | 7 |
- | Advanced decompiler, data flow & C++ | 34 |
- | Symbols, references & strings | 18 |
- | Data types | 12 |
- | Data & type archives | 47 |
- | Comments, bookmarks, equates, registers & crypto constants | 13 |
- | P-code emulation (one-shot + sessions) | 26 |
- | Debugger (GUI only) | 40 |
- | Version Tracking, program diff & function comparison | 30 |
- | Function ID & BSim | 27 |
- | File systems & executable formats (PE / ELF / Mach-O) | 43 |
- | Import / export, PDB / DWARF, YARA & reports | 35 |
- | Malware & reverse-engineering triage | 24 |
- | Ghidra scripts | 3 |
- | GUI basics + GUI control (GUI only) | 45 |
- | Utilities, tool discovery & bulk operations | 49 |
- | Additional tools | 33 |
- | **Total** | **679** |
- ## Configuration
- | Variable / option | Where | Default | Meaning |
- |---|---|---|---|
- | `GHIDRA_INSTALL_DIR` | build script, launchers | parent folder of the repo | Ghidra installation folder |
- | `GHIDRA_MCP_PORT` | GUI plugin | `8765` | Preferred port (the next free one is used if busy). Also `Edit > Tool Options > GhidraMCP` |
- | `GHIDRA_MCP_AUTOENABLE` | `ghidra-mcp-gui.bat` | `1` | `0` starts Ghidra without enabling the plugin automatically |
- | `GHIDRA_MCP_MAXMEM` | `ghidra-mcp-headless.bat` | `4G` | Java heap of the headless server |
- | `GHIDRA_MCP_URL` | bridge | auto-discovery | Fixed server URL, e.g. `http://127.0.0.1:8766` |
- | `GHIDRA_MCP_TIMEOUT` | bridge | `3600` | Per-call timeout in seconds |
- | `JAVA_HOME` | build scripts | `PATH` | JDK used to build |
- ## Security
- - The server listens on **127.0.0.1 only** and rejects requests coming from web pages (foreign `Origin` / `Host` headers).
- - There is **no authentication**: any local process can call it, and `run_script_inline` / `run_script` execute arbitrary
- code inside Ghidra with your user rights. Do not run it on a shared machine you do not trust; disable the plugin when you
- do not need it.
- - Tools that write files (exports, extraction, archives) write where they are told to. Review what your assistant does,
- as with any tool that has file-system access.
- - Emulation never executes the analysed program natively; the debugger tools do run it (on purpose) - use a VM for malware.
- ## Development
- ```
- GhidraMCP/
- ├─ src/ghidramcp/ Java sources: Tools.java (registry + helpers), McpServer.java (HTTP / MCP), GhidraMCPPlugin.java,
- │ HeadlessMain.java, GuiMain.java and one T_<Domain>.java per tool domain
- ├─ bridge/ stdio MCP bridge + tools.json (generated catalog)
- ├─ build.ps1 build + install (+ -Zip); ghidra-env.ps1 locates Ghidra and the JDK
- └─ ghidra-mcp-gui.bat, ghidra-mcp-headless.bat launchers
- ```
- **Adding a tool** - in the relevant `T_*.java`:
- ```java
- T.add("my_tool", R, // N: no program, R: reads a program, W: modifies it (auto transaction)
- "What it does, when to use it, what it returns.",
- P("function!|s|Function name or address", "limit|i|Max results (default 50)"), // name!|type|description
- a -> {
- Function f = a.func("function"); // helpers: a.addr(), a.dtype(), a.range(), page(), matcher(), m()
- return m("name", f.getName(), "size", f.getBody().getNumAddresses());
- });
- ```
- Return maps / lists of plain values (never raw Ghidra objects), throw `McpError` for user-facing errors, and paginate
- long lists. Then rebuild (with Ghidra closed):
- ```powershell
- powershell -ExecutionPolicy Bypass -File build.ps1
- ```
- ## Status and limitations
- - Tested with Ghidra 12.2 PUBLIC and JDK 25 on Windows 11, headless and through the GUI plugin.
- - The **debugger** and **GUI-control** tools need the GUI and have had less real-world use than the rest. Feedback welcome.
- - Scripts and launchers are Windows-only for now (the Java extension and the bridge are portable).
- - `run_script_inline` with `language: python` requires Ghidra started through PyGhidra.
- ## License
- MIT - see [LICENSE](LICENSE). Ghidra is a software reverse engineering framework created by the NSA, distributed under the
- Apache License 2.0; this project is not affiliated with the NSA or the Ghidra project.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.