ghidra-headless-mcp

Minimal headless MCP server for Ghidra. No GUI, no plugin, no HTTP bridge: it runs Ghidra in-process through PyGhidra. Sibling of Revoid (jadx) and uses the same tool style.

Install

Requires Python 3.9+, JDK 21+ and Ghidra 11.3+ (tested on 12.1).

pip install git+https://github.com/samudoria/ghidra-headless-mcp   # or the wheel from Releases

{
  "mcpServers": {
    "ghidra": {
      "command": "ghidra-headless-mcp",
      "env": { "GHIDRA_INSTALL_DIR": "/opt/ghidra" }
    }
  }
}

OpenCode

In opencode.json (project) or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ghidra": {
      "type": "local",
      "command": ["ghidra-headless-mcp"],
      "environment": { "GHIDRA_INSTALL_DIR": "/opt/ghidra" },
      "enabled": true
    }
  }
}

Related MCP server: REA (Reverse Engineer Anything)

Use with Revoid

For Android apps: in Revoid call list_native_libraries, then extract_native_library to get a .so path on disk, and pass that path to load_binary here. Each server keeps its own renames and comments. Tell the model to rename and comment as it goes; the notes are what the next analyst reads.

Tools

All lists take limit (default 50) and offset; the reply contains next_offset (null at the end). Edits are saved to the Ghidra project immediately and survive restarts: reloading the same file reopens your names and comments.

Load flow (non-blocking)

load_binary no longer blocks on Ghidra's multi-minute auto-analysis. The import is synchronous (seconds); full analysis then runs on a background thread. The intended agent flow:

1. load_binary(path) — returns at once with {"state":"analyzing"|"ready", ...}.

2. Read immediately, while analysis runs: list_exports, list_imports, list_strings, list_functions, read_memory, search_bytes — the structural questions (which exports? JNI functions? suspicious imports/strings?).

3. Poll load_status() until {"state":"ready","analyzed":true}.

4. Then call decompiler-driven tools: get_function, get_disassembly, get_callers/get_callees/get_xrefs, call_path, search_constants, rename*, retype_variable, set_signature, add_comment.

Called before analysis is done, a decompiler-driven tool returns a soft {"status":"analyzing","retry_after_s":N,"hint":...} — not an error and never an under-analyzed answer. With analyze=False, the first such call starts analysis itself (triage cheaply, pay for analysis only when you decompile). A re-analyzed cached project loads straight to ready with no re-analysis.

Environment

HTTP / SSE

GHIDRA_INSTALL_DIR=/opt/ghidra GHIDRA_MCP_TRANSPORT=sse ghidra-headless-mcp
# SSE endpoint:        http://127.0.0.1:8000/sse
# streamable-http:     GHIDRA_MCP_TRANSPORT=streamable-http  -> http://127.0.0.1:8000/mcp

{
  "mcpServers": {
    "ghidra": { "type": "sse", "url": "http://127.0.0.1:8000/sse" }
  }
}

One binary is loaded at a time; load_binary closes the previous one. Only one server may open a given project at a time. Logs go to stderr; stdout is reserved for the protocol.

Test

python tests/test_state.py                                                      # state machine, no Ghidra needed
GHIDRA_INSTALL_DIR=/opt/ghidra python tests/smoke.py ./some_binary some_function # end-to-end over stdio