Ghidra逆向工程MCP服务器

Prerequisites

• Java 21 LTS (OpenJDK recommended)
• Apache Maven 3.9+
• Ghidra 12.1.2 (or compatible version)
• Python 3.10+ with uv (recommended) or pip + venv

Shared Ghidra Server users: Ghidra 12.1.2 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.2 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.

Solution: ```text

Library Dependencies

Ghidra JARs must be installed into your local Maven repository (~/.m2/repository) before compilation. This is a one-time setup per machine, and again when your Ghidra version changes. -Deploy now installs these automatically by default.

The tool enforces version consistency between: - pom.xml (ghidra.version) - --ghidra-path version segment (e.g., ghidra_12.1.2_PUBLIC)

If these do not match, deployment fails fast with a clear error.

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
   

2. Recommended: run environment preflight first:

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

3. Build and deploy to Ghidra:

   python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_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.

4. 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.2_PUBLIC"
   

5. Show command help:

   python -m tools.setup --help
   

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

   python -m tools.setup build
   

Supported build path: python -m tools.setup build uses Maven under the hood and is the canonical workflow used by the repo tasks and docs.

   # Manual Maven build (requires Ghidra deps already installed in local .m2)
   mvn clean package assembly:single -DskipTests
   

   # Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
   GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension
   

Installation (Linux — Ubuntu/Debian)

1. Clone the repository:

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

2. 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
   > 

3. Run environment preflight:

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

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

   python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_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

5. Optional: setup only Maven dependencies:

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

6. 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
   

2. Clone the repository:

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

3. Install Ghidra JARs into local Maven:

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

4. 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
   

Note: --ghidra-version is required when using the Homebrew path because the path contains no version string.

5. Start Ghidra and enable the plugin:

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

6. Configure Cursor/Claude MCP (~/.cursor/mcp.json):

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

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

`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: ~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar 2. Or use: File > Install Extensions > Add and select the ZIP file 3. Ensure JAR/ZIP was built for your Ghidra version

Building from Source

```bash

Standard first-time setup and deploy

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

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

🚀 Quick Start

Basic Usage

#### Option 1: Stdio Transport (Recommended for AI tools)

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

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

autohand mcp add ghidra 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.

#### 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

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. To keep the model's tool surface small, run with --lazy (loads only listing,function,program on connect) and let 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 eager and --lazy modes, so agents that honor tools/list_changed get full discovery without the upfront context cost.

Optional: Connect a standalone debugger server

The debugger server itself moved to the d2-game-exe repository on 2026-08-11 (its D2 calling-convention layer made it game-specific). Start it there, then point this bridge at it:

export GHIDRA_DEBUGGER_URL=http://127.0.0.1:8099

The bridge's 22 debugger_* proxy tools register only when that variable is set, so leaving it unset costs nothing — the tools simply do not appear rather than appearing and failing.

Debugger server flags:

Set GHIDRA_DEBUGGER_URL in .env if you change the default port or host so the bridge can find it.

#### In Ghidra 1. Start Ghidra and open a CodeBrowser window 2. In CodeBrowser, enable the plugin via File > Configure > Configure All Plugins > GhidraMCP 3. Optional: configure custom port via CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server 4. Start the server via Tools > GhidraMCP > Start MCP Server 5. The server runs on http://127.0.0.1:8089/ by default

#### Verify It's Working ```bash

Example: exposing to a private LAN with auth

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

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

🛠️ API Reference

253 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.

Cross-References

• 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)
• get_bulk_xrefs - Get xrefs for multiple addresses
• get_function_xrefs - Get function cross-references
• 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

Version bump (updates all maintained version references atomically)

python -m tools.setup bump-version --new X.Y.Z ```

The authoritative build system today is Maven. tools.setup, the VS Code tasks, and the documented deploy flow all build through pom.xml and write artifacts to target/. build.gradle remains in the repo as a manual fallback for direct Ghidra/Gradle users, but it is not the primary path.

Command Reference

Common flags accepted by most commands:

Deploy test tiers are opt-in because benchmark tiers can import/reset Benchmark.dll and BenchmarkDebug.exe in the active Ghidra project. Use --test release before cutting releases, or set GHIDRA_MCP_DEPLOY_TESTS=release in a local .env when you want every deploy on your machine to run the live benchmark regression. See Testing and Release Regression.

```text

Core MCP Integration

• Full MCP Compatibility — Complete implementation of Model Context Protocol
• 253 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

Expected: "Connected: GhidraMCP plugin running with program '<name>'"

Components

• python/bridge_mcp_ghidra/ — Python MCP server package (ships as the ghidra-mcp-bridge wheel; bridge-mcp-ghidra console script) that translates MCP protocol to HTTP calls (225 catalog entries)
• GhidraMCP.jar — Ghidra plugin that exposes analysis capabilities via HTTP (175 GUI endpoints)
• GhidraMCPHeadlessServer — Standalone headless server — 183 endpoints, no GUI required
• ghidra_scripts/ — Collection of automation scripts for common tasks

Recommended: direct Python-first workflow

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

AI Workflow Prompts

• Function Documentation V5 — Primary workflow: 7-step process with Hungarian notation, type auditing, and verification scoring
• Batch Documentation V5 — Parallel subagent dispatch for multi-function processing
• Orphaned Code Discovery — Automated scanner for undiscovered functions
• Data Type Investigation — Structure discovery and field analysis
• Global Data Analysis — Global naming and analysis
• Quick Start Prompt — Simplifi

❓ Troubleshooting

Troubleshooting: Version Mismatch

If you see a version mismatch error, align both values: 1. pom.xml → ghidra.version 2. --ghidra-path version segment (ghidra_X.Y.Z_PUBLIC)

Then rerun:

python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

```text