PyGhidra-MCP - Ghidra Model Context Protocol Server

Overview

pyghidra-mcp is a command-line Model Context Protocol (MCP) server that brings the full analytical power of Ghidra, a robust software reverse engineering (SRE) suite, into the world of intelligent agents and LLM-based tooling.
It bridges Ghidra’s ProgramAPI and FlatProgramAPI to Python using pyghidra and jpype, then exposes that functionality via the Model Context Protocol.

MCP is a unified interface that allows language models, development tools (like VS Code), and autonomous agents to access structured context, invoke tooling, and collaborate intelligently. Think of MCP as the bridge between powerful analysis tools and the LLM ecosystem.

With pyghidra-mcp, Ghidra becomes an intelligent backend—ready to respond to context-rich queries, automate deep reverse engineering tasks, and integrate into AI-assisted workflows.

> [!NOTE]
> This beta project is under active development. We would love your feedback, bug reports, feature requests, and code.

Yet another Ghidra MCP?

Yes, the original ghidra-mcp is fantastic. But pyghidra-mcp takes a different approach:

- 🐍 No GUI required – Run entirely via CLI for streamlined automation and scripting.
- 🔁 Designed for automation – Ideal for integrating with LLMs, CI pipelines, and tooling that needs repeatable behavior.
- ✅ CI/CD friendly – Built with robust unit and integration tests for both client and server sessions.
- 🚀 Quick startup – Supports fast command-line launching with minimal setup.
- 📦 Project-wide analysis – Enables concurrent reverse engineering of all binaries in a Ghidra project
- 🤖 Agent-ready – Built for intelligent agent-driven workflows and large-scale reverse engineering automation.
- 🔍 Semantic code search – Uses vector embeddings (via ChromaDB) to enable fast, fuzzy lookup across decompiled functions, comments, and symbols—perfect for pseudo-C exploration and agent-driven triage.

This project provides a Python-first experience optimized for local development, headless environments, and testable workflows.

graph TD
    subgraph Clients
        A[🤖 LLM / Agent]
        B[💻 Local CLI User]
        C[🔧 CI/CD Pipeline]
    end
subgraph Startup Command

        direction LR

        cmd("pyghidra-mcp /path/to/binary1 /path/to/binary2")

    end
subgraph "pyghidra-mcp Server"

        D[MCP Server]

        E[pyghidra ]

        F[Ghidra Headless]
subgraph "Ghidra Project Analysis"

          G[Binary 1]

          H[Binary 2]

          I[...]

      end

    end
cmd --> D
A -- "MCP (stdio/http)" --> D

    B -- "stdio/http" --> D

    C -- "stdio/sse" --> D
D -- "Initializes" --> E

    E -- "Controls" --> F
F -- "Analyzes Concurrently" --> G

    F -- "Analyzes Concurrently" --> H

    F -- "Analyzes Concurrently" --> I
subgraph "Exposed MCP API"

        J[decompile_function]

        K[search_functions_by_name]

    end
D -- "Exposes Tools" --> J

    D -- "Exposes Tools" --> K
J -- "Results" --> A

    K -- "Results" --> A

Contents

- PyGhidra-MCP - Ghidra Model Context Protocol Server
- Overview
- Yet another Ghidra MCP?
- Contents
- Getting started
- Development
- Setup
- Testing and Quality
- API
- Tools
- Code Search
- Cross-References
- Decompile Function
- List Exports
- List Imports
- List Project Binaries
- List Project Program Info
- Search Functions
- Search Symbols
- Prompts
- Resources
- Usage
- Mapping Binaries with Docker
- Using with OpenWeb-UI and MCPO
- With uvx
- With Docker
- Standard Input/Output (stdio)
- Python
- Docker
- Streamable HTTP
- Python
- Docker
- Server-sent events (SSE)
- Python
- Docker
- Integrations
- Claude Desktop
- Inspiration
- Contributing, community, and running from source

Getting started

Run the Python package as a CLI command using uv:

uvx pyghidra-mcp # see --help for more options

Or, run as a Docker container:

docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

Development

This project uses a Makefile to streamline development and testing. ruff is used for linting and formatting, and pre-commit hooks are used to ensure code quality.

Setup

1. Install uv: If you don't have uv installed, you can install it using pip:

    pip install uv

    

2. Create a virtual environment and install dependencies:

    make dev-setup

    source ./.venv/bin/activate

    

3. Set Ghidra Environment Variable: Download and install Ghidra, then set the GHIDRA_INSTALL_DIR environment variable to your Ghidra installation directory.

    # For Linux / Mac

    export GHIDRA_INSTALL_DIR="/path/to/ghidra/"

# For Windows PowerShell

    [System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\ghidra_10.2.3_PUBLIC_20230208\ghidra_10.2.3_PUBLIC')

    

Testing and Quality

The Makefile provides several targets for testing and code quality:

- make test: Run the full test suite (unit and integration).
- make test-unit: Run unit tests.
- make test-integration: Run integration tests.
- make lint: Check code style with ruff.
- make format: Format code with ruff.
- make typecheck: Run type checking with ruff.
- make check: Run all quality checks.
- make dev: Run the development workflow (format and check).

API

Tools

Enable LLMs to perform actions, make deterministic computations, and interact with external services.

Code Search

- search_code(binary_name: str, query: str, limit: int = 10): Search for code within a binary by similarity using vector embeddings.

Cross-References

- list_cross_references(binary_name: str, name_or_address: str): Finds and lists all cross-references (x-refs) to a given function or address.

Decompile Function

- decompile_function(binary_name: str, name: str): Decompile a function from a given binary.

List Exports

- list_exports(binary_name: str, query: str | None = None, offset: int = 0, limit: int = 25): Lists all exported functions and symbols from a specified binary (regex supported for query).

List Imports

- list_imports(binary_name: str, query: str | None = None, offset: int = 0, limit: int = 25): Lists all imported functions and symbols for a specified binary (regex supported for query).

List Project Binaries

- list_project_binaries(): Lists the names of all binaries currently loaded in the Ghidra project.

List Project Program Info

- list_project_program_info(): Retrieves detailed information for all programs (binaries) in the project.

Search Functions

- search_functions_by_name(binary_name: str, query: str, offset: int = 0, limit: int = 25): Search for functions within a binary by name (case-insensitive substring).

Search Symbols

- search_symbols_by_name(binary_name: str, query: str, offset: int = 0, limit: int = 25): Search for symbols within a binary by name (case-insensitive substring).

Prompts

Reusable prompts to standardize common LLM interactions.

- write_ghidra_script: Return a prompt to help write a Ghidra script.

Resources

Expose data and content to LLMs

- ghidra://program/{program_name}/function/{function_name}/decompiled: Decompiled code of a specific function.

Usage

This Python package is published to PyPI as pyghidra-mcp and can be installed and run with pip, pipx, uv, poetry, or any Python package manager.

$ pipx install pyghidra-mcp
$ pyghidra-mcp --help
Usage: pyghidra-mcp [OPTIONS]
Entry point for the MCP server
Supports both stdio and sse transports. For stdio, it will read from stdin

  and write to stdout. For sse, it will start an HTTP server on port 8000.
Options:

  -v, --version                Show version and exit.

  -t, --transport [stdio|sse|streamable-http]  Transport protocol to use (stdio, sse or streamable-http)

  -h, --help                   Show this message and exit.

Mapping Binaries with Docker

When using the Docker container, you can map a local directory containing your binaries into the container's workspace. This allows pyghidra-mcp to analyze your files.

```bash