Ghidra逆向工程MCP服务器

Prerequisites

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

Shared Ghidra Server users: Ghidra 12.1 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 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_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_PUBLIC"
   

3. Build and deploy to Ghidra:

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

3. Run environment preflight:

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

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

   python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1_PUBLIC
   python -m tools.setup build
   python -m tools.setup deploy --ghidra-path ~/ghidra_12.1_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_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", "--script", "/path/to/ghidra-mcp/bridge_mcp_ghidra.py"]
       }
     }
   }
   

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

Extension not appearing in Install Extensions

Cause: JAR file in wrong location.

Solution: 1. Manual install location: ~/.ghidra/ghidra_12.1_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_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1_PUBLIC"

Preflight check before deploying

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

🐳 Headless Server (Docker)

GhidraMCP includes a headless server mode for automated analysis without the Ghidra GUI.

Quick Start with Docker

```bash

Build and run

docker-compose up -d ghidra-mcp

4. Decompile a function

curl "http://localhost:8089/decompile_function?address=0x401000"

🚀 Quick Start

Basic Usage

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

python bridge_mcp_ghidra.py

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

python bridge_mcp_ghidra.py --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"
    }
  }
}

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

python bridge_mcp_ghidra.py --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

Bridge advanced flags

#### Optional: Start the standalone debugger server

python -m pip install -r requirements-debugger.txt
python -m debugger

The debugger server listens on http://127.0.0.1:8099/ by default and is required for the debugger_* proxy tools exposed by the MCP bridge.

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

Quick Start

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Build and test your changes (mvn clean package assembly:single -DskipTests or GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. Update documentation as needed
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Configuration

Environment variables for Docker: - GHIDRA_MCP_PORT - Server port (default: 8089) - GHIDRA_MCP_BIND_ADDRESS - Bind address (default: 0.0.0.0 in Docker) - JAVA_OPTS - JVM options (default: -Xmx4g -XX:+UseG1GC)

🛠️ API 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

Headless API Workflow

```bash

Key Headless Endpoints

Core MCP Integration

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

`python -m debugger` fails with `ModuleNotFoundError` for `pybag` or `comtypes`

Cause: The standalone debugger server uses optional Windows-only Python dependencies that are not installed by the base requirements file.

Solution:

python -m pip install -r requirements-debugger.txt
python -m debugger

If you have both a global Python and a project venv, make sure you install into and run from the same interpreter.

Components

• bridge_mcp_ghidra.py — Python MCP server 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_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1_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 — Systematic structure discovery
• Cross-Version Matching — Hash-based function matching
• Quick Start Prompt — Simplified beginner workflow
• All Prompts — Complete prompt index

❓ 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_PUBLIC"

```text