ghidra-mcp

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