Ghidra逆向工程MCP服务器

Prerequisites

• Java 21 LTS (OpenJDK recommended)
• Apache Maven 3.9+ for the python -m tools.setup commands below (Maven is their default backend). Not needed if you build with the committed Gradle wrapper instead — see step 6
• Ghidra 12.1.4 (or compatible version)
• Python 3.10+ with uv (recommended) or pip + venv

Shared Ghidra Server users: Ghidra 12.1.4 clients require a Ghidra Server at 12.1, 12.0.5, or a newer compatible version. Upgrade the server before using this plugin from a 12.1 client. Ghidra 12.1.4 ships Jython as an optional extension. Java scripts work by default, but .py scripts in ghidra_scripts/ require installing the Jython extension from File > Install Extensions and restarting Ghidra.

Build fails with "Ghidra dependencies not found"

Cause: Ghidra JARs not installed in local Maven repository (Maven backend only; Gradle reads them straight from the installation).

Solution:

```text

Quickstart: install a release (no clone, no build)

Every release ships the two pieces you need: the Ghidra extension (GhidraMCP-<version>.zip) and the MCP bridge (ghidra_mcp_bridge-<version>-py3-none-any.whl).

1. Install the prerequisites: Ghidra 12.1.4, Java 21 and uv. The extension only loads in the exact Ghidra version it was built for. 2. Install the extension: in Ghidra's project window, File > Install Extensions, click +, pick the GhidraMCP-<version>.zip you downloaded, and restart Ghidra. 3. Enable the plugin: in the project window, File > Configure > Utility > Configure, tick GhidraMCPPlugin. Check it answers:

   curl http://127.0.0.1:8089/check_connection
   # {"status": "ok", "server_kind": "gui", "version": "7.0.0"}
   

1. Install the bridge (copy the wheel's link from the same release page):

   uv tool install https://github.com/bethington/ghidra-mcp/releases/download/v7.0.0/ghidra_mcp_bridge-7.0.0-py3-none-any.whl
   

5. Point your MCP client at it, using the absolute path (`which bridge-mcp-ghidra, or where.exe bridge-mcp-ghidra` on Windows):

   {
     "mcpServers": {
       "ghidra-mcp": { "command": "/home/<you>/.local/bin/bridge-mcp-ghidra" }
     }
   }
   

On Windows: "command": "C:\\Users\\<you>\\.local\\bin\\bridge-mcp-ghidra.exe". A client launched from a GUI or a service does not see your shell's PATH, so a bare bridge-mcp-ghidra fails with spawn ENOENT.

Open a program in Ghidra and ask your AI tool to list its functions. Screenshots of steps 2-3: docs/INSTALL_GUI.md. Building from source, Docker, the HTTP transports and every bridge flag are further down.

Which version should I run? Tagged releases (7.0.0, 7.1.0, ...) are stable. Release candidates and main are beta: feature-complete and live-tested, but shapes can still change before final. dev is experimental: tools are merged, renamed and refactored there freely, so build nothing on its API.

🚀 Install from source

The Quickstart above needs none of this. Build from source to run dev, to contribute, or to use python -m tools.setup deploy, which installs, configures and restarts Ghidra for you.

Installation

Recommended for all platforms: use python -m tools.setup directly. ensure-prereqs installs runtime Python requirements plus the Ghidra JARs needed in the local Maven repository. deploy copies the build output, installs the user-profile extension, and patches Ghidra user config.

1. Clone the repository:

   git clone https://github.com/bethington/ghidra-mcp.git
   cd ghidra-mcp
   

1. Recommended: run environment preflight first:

   python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.4_PUBLIC"
   

1. Build and deploy to Ghidra:

   python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.4_PUBLIC"
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.4_PUBLIC"
   

deploy saves/closes an already-running matching Ghidra instance when needed, installs the extension, starts Ghidra, waits for MCP health, and runs schema smoke checks.

Prefer to click through Ghidra's own dialogs, or installing a release zip on a machine without the repo? Follow the illustrated manual GUI install guide.

1. Optional strict/manual mode (advanced):

   # Skip automatic prerequisite setup
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.4_PUBLIC"
   

1. Show command help:

   python -m tools.setup --help
   

1. Optional build-only mode (advanced/troubleshooting):

   python -m tools.setup build
   

Two Java backends are supported. Gradle is the default for local work — it reads Ghidra's jars straight out of the installation, so there is no install-file step and nothing to install beyond a JDK. CI builds and gates with Maven, so Maven is a maintained peer rather than a fallback.

   # Gradle (default) -- the wrapper is committed, so no Gradle install is needed.
   # -PGHIDRA_INSTALL_DIR or the GHIDRA_INSTALL_DIR env var both work.
   # In Git Bash use forward slashes; a backslash path is mangled before Gradle sees it.
   ./gradlew buildExtension -PGHIDRA_INSTALL_DIR=/path/to/ghidra
   

   # Maven (peer backend; what CI uses). Needs Ghidra's jars in the local .m2 first:
   #   python -m tools.setup ensure-prereqs --ghidra-path /path/to/ghidra
   mvn clean package assembly:single -DskipTests
   

python -m tools.setup build routes to Maven by default; set TOOLS_SETUP_BACKEND=gradle to route it to Gradle instead.

Installation (Linux — Ubuntu/Debian)

1. Clone the repository:

   git clone https://github.com/bethington/ghidra-mcp.git
   cd ghidra-mcp
   

1. Install system prerequisites (if not already installed):

   sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   

Debian/Kali/Ubuntu 23.04+ note (PEP 668): these distros mark the system > Python as externally managed, so a bare pip install fails with > error: externally-managed-environment. Don't work around it with > --break-system-packages — it can corrupt apt-managed tooling. Instead use > uv (recommended — it creates and manages a > project-local .venv automatically, and is what this repo's commands use): > >

   > curl -LsSf https://astral.sh/uv/install.sh | sh
   > uv run bridge-mcp-ghidra    # resolves deps into .venv and starts the bridge
   > 

> > or a classic virtual environment: > >

   > python3 -m venv .venv && source .venv/bin/activate
   > pip install -e .
   > bridge-mcp-ghidra
   > 

1. Run environment preflight:

   python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.4_PUBLIC
   

1. Build and deploy to Ghidra (single command):

   python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.4_PUBLIC
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.4_PUBLIC
   

This will: - Install Ghidra JAR dependencies into your local ~/.m2/repository - Build GhidraMCP-<version>.zip with Maven - Extract the extension to ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/ - Update preferences with LastExtensionImportDirectory - Install Python requirements

1. Optional: setup only Maven dependencies:

   python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.4_PUBLIC
   

1. Show command help:

   python -m tools.setup --help
   

Linux paths: The extension is installed to $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/. Ghidra config files are in $HOME/.config/ghidra/ghidra_<version>_PUBLIC/.

Installation (macOS — Homebrew)

1. Install prerequisites:

   brew install openjdk@21 maven python ghidra
   

1. Clone the repository:

   git clone https://github.com/bethington/ghidra-mcp.git
   cd ghidra-mcp
   

1. Install Ghidra JARs into local Maven:

    python -m tools.setup install-ghidra-deps \
       --ghidra-path /opt/homebrew/opt/ghidra/libexec
   

1. Build and deploy:

    python -m tools.setup ensure-prereqs \
       --ghidra-path /opt/homebrew/opt/ghidra/libexec
    python -m tools.setup build
    python -m tools.setup deploy \
       --ghidra-path /opt/homebrew/opt/ghidra/libexec
   

The extension is installed to ~/Library/ghidra/ghidra_12.1.4_PUBLIC/Extensions/GhidraMCP/.

Note: the Homebrew path contains no version string, so tools.setup reads the Ghidra version from Ghidra/application.properties inside the installation instead.

1. Start Ghidra and enable the plugin:

   /opt/homebrew/opt/ghidra/libexec/ghidraRun
   

The server starts with the plugin. Check it from the project window: Tools > GhidraMCP > Server Status

6. Configure Cursor/Claude MCP (~/.cursor/mcp.json) — use the absolute path to uv (which uv), not the bare name; GUI-launched clients do not inherit your shell's PATH (#441):

   {
     "mcpServers": {
       "ghidra": {
         "command": "/opt/homebrew/bin/uv",
         "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"]
       }
     }
   }
   

macOS is the sharpest case: apps launched from Finder/Dock get launchd's PATH, which never contains ~/.local/bin or /opt/homebrew/bin.

Installation (Arch Linux — AUR)

@Pandoriaantje maintains community AUR packages:

• ghidra-mcp-git — tracks main
• ghidra-mcp — tracks tagged releases

Install with your AUR helper of choice, e.g.:

yay -S ghidra-mcp        # or ghidra-mcp-git

Fuller health: build details, uptime, open program count, HTTP pool, memory

curl http://127.0.0.1:8089/mcp/health

classpath too -- docker/entrypoint.sh builds exactly that command.

java -cp "target/GhidraMCP-<version>.jar:<ghidra jars>" \ com.xebyte.headless.GhidraMCPHeadlessServer --bind 0.0.0.0 --port 8089 ```

The headless server serves only its Unix domain socket unless --port or --bind is given; either one adds the TCP listener.

`pip install` fails with `error: externally-managed-environment`

Cause: PEP 668. Debian-family distros (Debian 12+, Kali, Ubuntu 23.04+) mark the system Python as externally managed, so global pip install is blocked to protect apt-managed packages.

Solution: Use a virtual environment — never --break-system-packages. The recommended path is uv, which manages a project-local .venv automatically:

curl -LsSf https://astral.sh/uv/install.sh | sh
cd ghidra-mcp
uv run bridge-mcp-ghidra

Or a classic venv:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

Extension not appearing in Install Extensions

Cause: JAR file in wrong location.

Solution:

1. Manual install location: ~/.config/ghidra/ghidra_12.1.4_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar (%APPDATA%\ghidra\... on Windows, ~/Library/ghidra/... on macOS) 2. Or use: File > Install Extensions > Add and select the ZIP file — see the illustrated guide 3. Ensure JAR/ZIP was built for your Ghidra version

Functions: Decompile, Rename, Prototypes & Variables

• add_function_tag - Attach tags to ONE function (function + tags) OR MANY in one transaction (assignments=[{function,tags}, ...])
• batch_rename_function_components - Batch rename function components
• clear_flow_and_repair - Run Ghidra's GUI 'Clear Flow and Repair' action on a seed range: clears instruction flow reachable from the seed, then repairs function bodies and re-disassembles retained flow (ClearFlowAndRepairCmd with clear_data=false, clear_labels=false, repair=true)
• clear_instruction_flow_override - Clear flow override
• create_function - Create function at address
• delete_function - Delete function at address
• delete_function_tag - Delete a program-wide function tag definition
• disassemble_bytes - Disassemble byte range
• disassemble_function - Disassemble function
• force_decompile - Force fresh decompilation (output stamped with language_id + variant; optional variant= is checked against the loaded one)
• get_functions - Everything about one or many functions in a single call
• list_class_members - List the member functions of a C++ class
• list_function_tags - List all program-wide function tag definitions with their use counts
• remove_function_tag - Detach one or more tags from a function
• rename_function - Rename function by name
• rename_variables - Batch rename variables
• set_function_no_return - Set no-return attribute
• set_function_prototype - Set function prototype (return type, param types, calling convention)
• set_function_tag_comment - Update the comment/description on an existing program-wide function tag
• set_function_this_type - Set the decompiler/database type of the implicit 'this' pointer (ECX on x86 thiscall/fastcall)
• set_variable_storage - Set variable storage
• set_variable_type - Set the data type of a function variable (local OR parameter) by name at the decompiler (high-level) layer
• set_variables - Set types and names for multiple variables atomically

Basic Usage

Option 1: Stdio Transport (Recommended for AI tools)

uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

MCP client config (.mcp.json, ~/.cursor/mcp.json, Claude Desktop config, …). Use the absolute path to uv — see the note below for why:

{
  "mcpServers": {
    "ghidra-mcp": {
      "command": "/home/<you>/.local/bin/uv",
      "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra", "--transport", "stdio"],
      "env": { "GHIDRA_MCP_URL": "http://127.0.0.1:8089" }
    }
  }
}

On Windows the same config points at uv.exe, e.g. "command": "C:\\Users\\<you>\\.local\\bin\\uv.exe". Find your own path with which uv (POSIX) or where.exe uv (Windows), or just run python -m tools.setup preflight, which prints the resolved absolute path and a ready-to-paste snippet.

Why absolute? "command": "uv" fails under service and GUI launchers. The MCP client resolves command with its own PATH, not your shell's. A client started from a systemd user service, a .desktop entry, or any other GUI session inherits that launcher's environment, which routinely lacks ~/.local/bin and ~/.cargo/bin — the very directories uv installs into. The failure lands at process-spawn time as spawn uv ENOENT, before any bridge code runs, so there is nothing in any log to read. An absolute path makes the client's PATH irrelevant and works on the first try. The same applies to python, python3, and the bridge-mcp-ghidra console script. (#441)

To add the bridge to Autohand Code from a cloned checkout:

autohand mcp add ghidra /home/<you>/.local/bin/uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Add --scope project before ghidra to save the server in the current project's .autohand configuration instead of your user configuration.

Option 2: Streamable HTTP Transport (Recommended for web/HTTP clients)

uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

MCP client config for the HTTP transport (add to your client's MCP config file):

{
  "mcpServers": {
    "ghidra-mcp-http": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Browser-based clients (e.g. MCP Inspector) work out of the box: the HTTP transports answer CORS preflight (OPTIONS) requests and expose the mcp-session-id / mcp-protocol-version headers to scripts. Allowed origins mirror the Host-header policy — loopback on any port is always permitted, plus the bind host and any hosts listed in GHIDRA_MCP_ALLOWED_HOSTS.

GHIDRA_MCP_ALLOWED_HOSTS also supports clients that route a loopback-bound bridge through another network namespace. For example, a container can address the host as host.containers.internal without exposing the bridge on a LAN interface:

GHIDRA_MCP_ALLOWED_HOSTS=host.containers.internal \
  uv run bridge-mcp-ghidra --transport streamable-http \
  --mcp-host 127.0.0.1 --mcp-port 8081

The setting extends DNS-rebinding Host/Origin validation only; it does not change the bind address or make the listener reachable on additional interfaces.

Option 3: SSE Transport (Deprecated — use streamable-http instead)

uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

Bridge advanced flags

To require a token from MCP clients of an HTTP transport, set GHIDRA_MCP_INBOUND_TOKEN=<secret>; clients must then send Authorization: Bearer <secret>. The bridge logs a warning when it binds a non-loopback --mcp-host without one. Separately, when GHIDRA_MCP_AUTH_TOKEN (the token the bridge sends to Ghidra) is set and the bridge binds a non-loopback host, clients must present that same token, so the bridge cannot be used to relay it.

Lazy tool loading is the default (issue #440)

Advertising all 209 endpoints in a single tools/list is over a hard limit for at least one major provider. Gemini compiles function declarations into a constrained-decoding state machine and rejects the whole request before any tool is ever called:

400 INVALID_ARGUMENT
The specified schema produces a constraint that has too many states for serving

That is not a degradation, it is an outright break, and no client-side setting could work around a server that only ever offered the full set. So the bridge now loads listing,function,program (68 endpoints plus the 8 static tools) on connect and registers the rest on demand.

If your client ignores tools/list_changed it will not notice tools that are registered later, and should turn lazy loading off:

uv run bridge-mcp-ghidra --no-lazy          # when you control the command line
export GHIDRA_MCP_LAZY=0                    # when you don't (Docker, uvx, some client configs)

GHIDRA_MCP_LAZY accepts 0/false/no/off and 1/true/yes/on; an explicit --lazy/--no-lazy on the command line wins over it. Startup logs which mode is in effect.

Strict program routing (multi-program safety)

Set GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 to make the bridge refuse any program-scoped call that omits a program selector, returning a clear error instead of letting the call ride the server's shared "current program" (the one switch_program and the active GUI tab move).

export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1
uv run bridge-mcp-ghidra

Without this, a call that leaves program= out runs against whichever program is current, which is fine for a single-program workflow but a hazard once several programs are open: the call can read or edit the wrong binary with no error. The hazard is worse when more than one client shares a server, since each one moves that current-program global out from under the others.

With strict mode on, every program-scoped call must name its target. This covers every selector that picks an open program: plain program= and the cross-program tools' source_program/target_program or program_a/program_b (declared required, but the server still falls back to the current program when one arrives empty). A forgotten selector surfaces as a loud error on the first bad call instead of a silent write to the wrong binary. Tools with no program selector (open_program and close_program take path/name) are unaffected. Off by default: with the variable unset the bridge sends calls unchanged.

Reducing tool-context overhead

The bridge exposes a large catalog, so it loads only listing,function,program on connect (see above) and lets the model discover the rest on demand instead of registering everything:

- search_tools("rename function") — keyword-search the entire catalog, including tools whose group isn't loaded. Each result says whether it's callable now and, if not, the exact load_tool_group(...) call to enable it. - list_tool_groups() — list all categories and their load state. - load_tool_group("datatype") / unload_tool_group("datatype") — load or drop a category at runtime. - check_tools("rename_symbol,batch_set_comments") — confirm specific tools are callable right now.

search_tools works in both lazy and --no-lazy modes, so agents that honor tools/list_changed get full discovery without the upfront context cost.

Minimal read-only allowlist

Some MCP clients gate tools through an explicit allowlist. Cut it too far and the agent loses discovery — it cannot find entry points or enumerate functions through MCP, so it works around the allowlist by curl-ing the HTTP API on 127.0.0.1:8089 directly, which defeats the point of having one. The allowlist has to be small and self-sufficient.

Minimum viable read-only set (4 tools):

That set is genuinely closed: get_entry_points and find_functions supply the addresses and names that get_functions consumes, and its callees field names the next functions to feed straight back into it.

The three tools suggested in #441 were get_metadata, get_entry_points and decompile_function. The first two still exist under those names; decompile_function was folded into get_functions in 7.0.0 (fields=decompiled_code), and the migration guide maps every other removed name. find_functions is the one addition worth making: without it the agent can only reach code that is reachable by name from something it already decompiled, so anything not referenced from an entry point is invisible.

Useful next additions, in order:

Every tool above is a GET; none of them writes to the Ghidra database.

Two things to check when your allowlist is narrow:

- Groups, not just names. The bridge registers tools by group, and the group is the category on the Java @McpTool annotation (which the running server publishes at /mcp/schema) — not the category field in tests/endpoints.json, which is a separate hand-maintained column and does not always agree. All four tools in the minimum set fall inside the default listing,function,program groups, so they are registered even under --lazy. Of the additions above, only the xref ones fall outside: under --lazy you must either allow load_tool_group as well, or start the bridge with --default-groups listing,function,program,xref. - A narrow allowlist plus --lazy needs the group tools. If you allowlist only leaf tools and run lazily, the agent has no way to load anything else. Either run eagerly (--no-lazy; lazy is the default) or add search_tools, list_tool_groups, load_tool_group, and check_tools to the allowlist.

Verify any allowlist against the running server rather than against this table: curl http://127.0.0.1:8089/mcp/schema lists every tool with the category the bridge groups it by.

Optional: Connect an external debugger server

The bridge can proxy 22 debugger_* tools to an external dbgeng/WinDbg debugger server speaking the bridge's debugger HTTP API. That server is not part of this repository; this repo ships only the proxies. They are off by default and register only when you opt in:

```bash

Example: exposing to a private LAN with auth

```bash export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32) export GHIDRA_MCP_ALLOW_SCRIPTS=1 # only if your workflow needs it export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

🛠️ API Reference

209 MCP tools backed by HTTP endpoints, grouped by catalog category. Generated from tests/endpoints.json by python -m tools.gen_readme_api_reference --write; the live schema at /mcp/schema is authoritative at runtime. Usage patterns: docs/prompts/TOOL_USAGE_GUIDE.md.

186 of these are served by both the GUI plugin and the standalone headless server. The rest are marked (GUI only) (19) or (headless only) (4) — calling one against the other server returns a 404, not an error message. See python -m tools.audit_server_scope for how the split is derived.

Cross-References & Call Graphs

• add_memory_reference - Create a user-defined cross-reference between two memory addresses that the auto-analyzer can't infer (runtime-populated pointer tables, vtables, late-bound function pointers, missed jump/switch tables)
• analyze_call_graph - Analyze function call graph patterns
• get_assembly_context - Get assembly context
• get_full_call_graph - Get full call graph
• get_function_call_graph - Get call graph
• get_xrefs_from - Get references from address
• get_xrefs_to - Get references to address
• remove_reference - Remove memory cross-reference(s) from one address to another — the inverse of add_memory_reference

Core MCP Integration

• Full MCP Compatibility — Complete implementation of Model Context Protocol
• 209 MCP tools — Comprehensive API surface covering every aspect of binary analysis
• Production-Ready Reliability — Atomic transactions, batch operations, configurable timeouts
• Real-time Analysis — Live integration with Ghidra's analysis engine

Compatibility note: MCP tool names are normalized for GitHub Copilot CLI and CAPI validation. Exposed tool names use lowercase letters, digits, underscores, and hyphens only; nested HTTP paths such as /debugger/status are advertised as names like debugger_status_2 when needed to avoid collisions with static bridge tools.

AI-Powered Reverse Engineering Workflows

• Function Documentation Workflow V5 — 7-step process for complete function documentation with Hungarian notation, type auditing, and automated verification scoring
• Batch Documentation — Parallel subagent dispatch for documenting multiple functions simultaneously
• Orphaned Code Discovery — Automated scanner finds undiscovered functions in gaps between known code
• Data Type Investigation — Systematic workflows for structure discovery and field analysis
• Cross-Version Matching — Hash-based function matching across different binary versions

Headless server (`mvn clean package -P headless -DskipTests`). The jar does not

❓ Troubleshooting