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

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

Install uv: If you don't have uv installed, you can install it using pip:
```
pip install uv
```
Or, follow the official uv installation guide: https://docs.astral.sh/uv/install/
Create a virtual environment and install dependencies:
```
make dev-setup
source ./.venv/bin/activate
```

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.

Read Bytes

read_bytes(binary_name: str, address: str, size: int = 32): Reads raw bytes from memory at a specified address. Returns raw hex data. Useful for inspecting memory contents, data structures, or confirming analysis findings.

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.

# Create and populate the new directory
mkdir -p ./binaries
cp /path/to/your/binaries/* ./binaries/

# Run the Docker container with volume mapping
docker run -i --rm \
  -v "$(pwd)/binaries:/binaries" \
  ghcr.io/clearbluejar/pyghidra-mcp \
  /binaries/*

Using with OpenWeb-UI and MCPO

You can integrate pyghidra-mcp with OpenWeb-UI using MCPO, an MCP-to-OpenAPI proxy. This allows you to expose pyghidra-mcp's tools through a standard RESTful API, making them accessible to web interfaces and other tools.

openweb.mp4

With `uvx`

You can run pyghidra-mcp and mcpo together using uvx:

uvx mcpo -- \
  pyghidra-mcp /bin/ls

With Docker

You can combine mcpo with Docker:

uvx mcpo -- docker run  ghcr.io/clearbluejar/pyghidra-mcp /bin/ls

Standard Input/Output (stdio)

The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools. See the spec for more details.

Python

pyghidra-mcp

By default, the Python package will run in stdio mode. Because it's using the standard input and output streams, it will look like the tool is hanging without any output, but this is expected.

Docker

This server is published to Github's Container Registry (ghcr.io/clearbluejar/pyghidra-mcp)

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

By default, the Docker container is in SSE mode, so you will have to include -t stdio after the image name and run with -i to run in interactive mode.

Streamable HTTP

Streamable HTTP enables streaming responses over JSON RPC via HTTP POST requests. See the spec for more details.

By default, the server listens on 127.0.0.1:8000/mcp for client connections. To change any of this, set FASTMCP_* environment variables. The server must be running for clients to connect to it.

Python

pyghidra-mcp -t streamable-http

By default, the Python package will run in stdio mode, so you will have to include -t streamable-http.

Docker

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

Server-sent events (SSE)

Warning

The MCP communiity considers this a legacy transport portcol and is really intended for backwards compatibility. Streamable HTTP is the recommended replacement.

SSE transport enables server-to-client streaming with Server-Send Events for client-to-server and server-to-client communication. See the spec for more details.

By default, the server listens on 127.0.0.1:8000/sse for client connections. To change any of this, set FASTMCP_* environment variables. The server must be running for clients to connect to it.

Python

pyghidra-mcp -t sse

By default, the Python package will run in stdio mode, so you will have to include -t sse.

Docker

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

Integrations

Note

This section is a work in progress. We will be adding examples for specific integrations soon.

Claude Desktop

Add the following JSON block to your claude_desktop_config.json file:

{
  "mcpServers": {
    "pyghidra-mcp": {
      "command": "uvx",
      "args": ["pyghidra-mcp", "/bin/ls", "/bin/jq", "/path/to/bin" ],
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
      }
    }
  }
}

Inspiration

This project implementation and design was inspired by these awesome projects:

Contributing, community, and running from source

We believe the future of reverse engineering is agentic, contextual, and scalable.
pyghidra-mcp is a step toward that future—making full Ghidra projects accessible to AI agents and automation pipelines.

We’re actively developing the project and welcome feedback, issues, and contributions.

Note

We love your feedback, bug reports, feature requests, and code.

Contributor workflow

If you're adding a new tool or integration, here’s the recommended workflow:

Label your branch with the prefix feature/ to indicate a new capability.
Add your tool using the same style and structure as existing tools in pyghidra/tools/.
Write an integration test that exercises your tool using a StdioClient instance. Place it in tests/integration/.
Extend concurrent testing by adding a call to your tool in tests/integration/test_concurrent_streamable_client.py.
Run make test and make format to ensure your changes pass all tests and conform to linting rules.

This ensures consistency across the codebase and helps us maintain robust, scalable tooling for reverse engineering workflows.

Made with ❤️ by the PyGhidra-MCP Team

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.vscode		.vscode
src/pyghidra_mcp		src/pyghidra_mcp
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

clearbluejar/pyghidra-mcp

Folders and files

Latest commit

History

Repository files navigation

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

Read Bytes

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

Contributor workflow

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

With `uvx`

Packages