<p align="center">
<img src="https://github.com/user-attachments/assets/31c1831a-5be1-4698-8171-5ebfc9d6797c" width=60% >
</p>
<p align="center">
<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/actions/workflows/pytest-devcontainer-repo-all.yml?label=pytest&style=for-the-badge">
<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
</p>
# 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](https://ghidra-sre.org/), a robust software reverse engineering (SRE) suite, into the world of intelligent agents and LLM-based tooling.
It bridges Ghidra’s [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) and [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) 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](https://github.com/LaurieWired/GhidraMCP) 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.
```mermaid
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](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Overview](#overview)
- [Yet another Ghidra MCP?](#yet-another-ghidra-mcp)
- [Contents](#contents)
- [Getting started](#getting-started)
- [Development](#development)
- [Setup](#setup)
- [Testing and Quality](#testing-and-quality)
- [API](#api)
- [Tools](#tools)
- [Code Search](#code-search)
- [Cross-References](#cross-references)
- [Decompile Function](#decompile-function)
- [List Exports](#list-exports)
- [List Imports](#list-imports)
- [List Project Binaries](#list-project-binaries)
- [List Project Program Info](#list-project-program-info)
- [Search Functions](#search-functions)
- [Search Symbols](#search-symbols)
- [Prompts](#prompts)
- [Resources](#resources)
- [Usage](#usage)
- [Mapping Binaries with Docker](#mapping-binaries-with-docker)
- [Using with OpenWeb-UI and MCPO](#using-with-openweb-ui-and-mcpo)
- [With `uvx`](#with-uvx)
- [With Docker](#with-docker)
- [Standard Input/Output (stdio)](#standard-inputoutput-stdio)
- [Python](#python)
- [Docker](#docker)
- [Streamable HTTP](#streamable-http)
- [Python](#python-1)
- [Docker](#docker-1)
- [Server-sent events (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-2)
- [Integrations](#integrations)
- [Claude Desktop](#claude-desktop)
- [Inspiration](#inspiration)
- [Contributing, community, and running from source](#contributing-community-and-running-from-source)
## Getting started
Run the [Python package](https://pypi.org/p/pyghidra-mcp) as a CLI command using [`uv`](https://docs.astral.sh/uv/guides/tools/):
```bash
uvx pyghidra-mcp # see --help for more options
```
Or, run as a [Docker container](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
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:
```bash
pip install uv
```
Or, follow the official `uv` installation guide: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **Create a virtual environment and install dependencies**:
```bash
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.
```bash
# 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](https://pypi.org/p/pyghidra-mcp) and can be installed and run with [pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package), [pipx](https://pipx.pypa.io/), [uv](https://docs.astral.sh/uv/), [poetry](https://python-poetry.org/), or any Python package manager.
```text
$ 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
# 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](https://github.com/open-webui/open-webui) using [MCPO](https://github.com/open-webui/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.
https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95
#### With `uvx`
You can run `pyghidra-mcp` and `mcpo` together using `uvx`:
```bash
uvx mcpo -- \
pyghidra-mcp /bin/ls
```
#### With Docker
You can combine mcpo with Docker:
```bash
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](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) for more details.
#### Python
```bash
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](http://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](https://docs.docker.com/reference/cli/docker/container/run/#interactive) mode.
### Streamable HTTP
Streamable HTTP enables streaming responses over JSON RPC via HTTP POST requests. See the [spec](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) for more details.
By default, the server listens on [127.0.0.1:8000/mcp](https://127.0.0.1/mcp) for client connections. To change any of this, set [FASTMCP_*](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/server.py#L78) environment variables. _The server must be running for clients to connect to it._
#### Python
```bash
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](#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](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) for more details.
By default, the server listens on [127.0.0.1:8000/sse](https://127.0.0.1/sse) for client connections. To change any of this, set [FASTMCP_*](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/server.py#L78) environment variables. _The server must be running for clients to connect to it._
#### Python
```bash
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:
```json
{
"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:
* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
* [semgrep-mcp](https://github.com/semgrep/mcp)
* [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)
* [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)
## 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.
______________________________________________________________________
Made with ❤️ by the [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)
Raw data
{
"_id": null,
"home_page": null,
"name": "pyghidra-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "dynamic-analysis, ghidra, mcp, pyghidra, reverse-engineering, security, static-analysis",
"author": null,
"author_email": "clearbluejar <3752074+clearbluejar@users.noreply.github.com>, notoriousrip <3935212+unimpossible@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/96/77/c23f6e4f44ca53755db4bc86efd39835d9f87ba0028ca8738d706778cf8a/pyghidra_mcp-0.1.9.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/user-attachments/assets/31c1831a-5be1-4698-8171-5ebfc9d6797c\" width=60% >\n</p>\n\n<p align=\"center\">\n <img align=\"center\" alt=\"GitHub Workflow Status (with event)\" src=\"https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/actions/workflows/pytest-devcontainer-repo-all.yml?label=pytest&style=for-the-badge\">\n <img align=\"center\" alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge\">\n <img align=\"center\" src=\"https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge\">\n</p>\n\n# PyGhidra-MCP - Ghidra Model Context Protocol Server\n\n\n### Overview\n\n**`pyghidra-mcp`** is a command-line Model Context Protocol (MCP) server that brings the full analytical power of [Ghidra](https://ghidra-sre.org/), a robust software reverse engineering (SRE) suite, into the world of intelligent agents and LLM-based tooling.\nIt bridges Ghidra\u2019s [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) and [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) to Python using `pyghidra` and `jpype`, then exposes that functionality via the Model Context Protocol. \n\nMCP 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. \n\nWith `pyghidra-mcp`, Ghidra becomes an intelligent backend\u2014ready to respond to context-rich queries, automate deep reverse engineering tasks, and integrate into AI-assisted workflows.\n\n\n> [!NOTE]\n> This beta project is under active development. We would love your feedback, bug reports, feature requests, and code.\n\n## Yet another Ghidra MCP?\n\nYes, the original [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) is fantastic. But `pyghidra-mcp` takes a different approach:\n\n- \ud83d\udc0d **No GUI required** \u2013 Run entirely via CLI for streamlined automation and scripting.\n- \ud83d\udd01 **Designed for automation** \u2013 Ideal for integrating with LLMs, CI pipelines, and tooling that needs repeatable behavior.\n- \u2705 **CI/CD friendly** \u2013 Built with robust unit and integration tests for both client and server sessions.\n- \ud83d\ude80 **Quick startup** \u2013 Supports fast command-line launching with minimal setup.\n- \ud83d\udce6 **Project-wide analysis** \u2013 Enables concurrent reverse engineering of all binaries in a Ghidra project\n- \ud83e\udd16 **Agent-ready** \u2013 Built for intelligent agent-driven workflows and large-scale reverse engineering automation.\n- \ud83d\udd0d Semantic code search \u2013 Uses vector embeddings (via ChromaDB) to enable fast, fuzzy lookup across decompiled functions, comments, and symbols\u2014perfect for pseudo-C exploration and agent-driven triage.\n\nThis project provides a Python-first experience optimized for local development, headless environments, and testable workflows.\n\n```mermaid\ngraph TD\n subgraph Clients\n A[\ud83e\udd16 LLM / Agent]\n B[\ud83d\udcbb Local CLI User]\n C[\ud83d\udd27 CI/CD Pipeline]\n end\n\n subgraph Startup Command\n direction LR\n cmd(\"`pyghidra-mcp /path/to/binary1 /path/to/binary2`\")\n end\n\n subgraph \"pyghidra-mcp Server\"\n D[MCP Server]\n E[pyghidra ]\n F[Ghidra Headless]\n\n subgraph \"Ghidra Project Analysis\"\n G[Binary 1]\n H[Binary 2]\n I[...]\n end\n end\n\n\n\n cmd --> D\n\n A -- \"MCP (stdio/http)\" --> D\n B -- \"stdio/http\" --> D\n C -- \"stdio/sse\" --> D\n\n D -- \"Initializes\" --> E\n E -- \"Controls\" --> F\n\n F -- \"Analyzes Concurrently\" --> G\n F -- \"Analyzes Concurrently\" --> H\n F -- \"Analyzes Concurrently\" --> I\n\n subgraph \"Exposed MCP API\"\n J[decompile_function]\n K[search_functions_by_name]\n end\n\n D -- \"Exposes Tools\" --> J\n D -- \"Exposes Tools\" --> K\n\n J -- \"Results\" --> A\n K -- \"Results\" --> A\n```\n\n## Contents\n\n- [PyGhidra-MCP - Ghidra Model Context Protocol Server](#pyghidra-mcp---ghidra-model-context-protocol-server)\n - [Overview](#overview)\n - [Yet another Ghidra MCP?](#yet-another-ghidra-mcp)\n - [Contents](#contents)\n - [Getting started](#getting-started)\n - [Development](#development)\n - [Setup](#setup)\n - [Testing and Quality](#testing-and-quality)\n - [API](#api)\n - [Tools](#tools)\n - [Code Search](#code-search)\n - [Cross-References](#cross-references)\n - [Decompile Function](#decompile-function)\n - [List Exports](#list-exports)\n - [List Imports](#list-imports)\n - [List Project Binaries](#list-project-binaries)\n - [List Project Program Info](#list-project-program-info)\n - [Search Functions](#search-functions)\n - [Search Symbols](#search-symbols)\n - [Prompts](#prompts)\n - [Resources](#resources)\n - [Usage](#usage)\n - [Mapping Binaries with Docker](#mapping-binaries-with-docker)\n - [Using with OpenWeb-UI and MCPO](#using-with-openweb-ui-and-mcpo)\n - [With `uvx`](#with-uvx)\n - [With Docker](#with-docker)\n - [Standard Input/Output (stdio)](#standard-inputoutput-stdio)\n - [Python](#python)\n - [Docker](#docker)\n - [Streamable HTTP](#streamable-http)\n - [Python](#python-1)\n - [Docker](#docker-1)\n - [Server-sent events (SSE)](#server-sent-events-sse)\n - [Python](#python-2)\n - [Docker](#docker-2)\n - [Integrations](#integrations)\n - [Claude Desktop](#claude-desktop)\n - [Inspiration](#inspiration)\n - [Contributing, community, and running from source](#contributing-community-and-running-from-source)\n\n## Getting started\n\nRun the [Python package](https://pypi.org/p/pyghidra-mcp) as a CLI command using [`uv`](https://docs.astral.sh/uv/guides/tools/):\n\n```bash\nuvx pyghidra-mcp # see --help for more options\n```\n\nOr, run as a [Docker container](https://ghcr.io/clearbluejar/pyghidra-mcp):\n\n```bash\ndocker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio\n```\n\n## Development\n\nThis 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.\n\n### Setup\n\n1. **Install `uv`**: If you don't have `uv` installed, you can install it using pip:\n ```bash\n pip install uv\n ```\n Or, follow the official `uv` installation guide: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)\n\n2. **Create a virtual environment and install dependencies**:\n ```bash\n make dev-setup\n source ./.venv/bin/activate\n ```\n\n3. **Set Ghidra Environment Variable**: Download and install Ghidra, then set the `GHIDRA_INSTALL_DIR` environment variable to your Ghidra installation directory.\n ```bash\n # For Linux / Mac\n export GHIDRA_INSTALL_DIR=\"/path/to/ghidra/\"\n\n # For Windows PowerShell\n [System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\\ghidra_10.2.3_PUBLIC_20230208\\ghidra_10.2.3_PUBLIC')\n ```\n\n### Testing and Quality\n\nThe `Makefile` provides several targets for testing and code quality:\n\n- `make test`: Run the full test suite (unit and integration).\n- `make test-unit`: Run unit tests.\n- `make test-integration`: Run integration tests.\n- `make lint`: Check code style with `ruff`.\n- `make format`: Format code with `ruff`.\n- `make typecheck`: Run type checking with `ruff`.\n- `make check`: Run all quality checks.\n- `make dev`: Run the development workflow (format and check).\n\n## API\n\n### Tools\n\nEnable LLMs to perform actions, make deterministic computations, and interact with external services.\n\n#### Code Search\n\n- `search_code(binary_name: str, query: str, limit: int = 10)`: Search for code within a binary by similarity using vector embeddings.\n\n#### Cross-References\n\n- `list_cross_references(binary_name: str, name_or_address: str)`: Finds and lists all cross-references (x-refs) to a given function or address.\n\n#### Decompile Function\n\n- `decompile_function(binary_name: str, name: str)`: Decompile a function from a given binary.\n\n#### List Exports\n\n- `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).\n\n#### List Imports\n\n- `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).\n\n#### List Project Binaries\n\n- `list_project_binaries()`: Lists the names of all binaries currently loaded in the Ghidra project.\n\n#### List Project Program Info\n\n- `list_project_program_info()`: Retrieves detailed information for all programs (binaries) in the project.\n\n#### Search Functions\n\n- `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).\n\n#### Search Symbols\n\n- `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).\n\n### Prompts\n\nReusable prompts to standardize common LLM interactions.\n\n- `write_ghidra_script`: Return a prompt to help write a Ghidra script.\n\n### Resources\n\nExpose data and content to LLMs\n\n- `ghidra://program/{program_name}/function/{function_name}/decompiled`: Decompiled code of a specific function.\n\n## Usage\n\nThis Python package is published to PyPI as [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) and can be installed and run with [pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package), [pipx](https://pipx.pypa.io/), [uv](https://docs.astral.sh/uv/), [poetry](https://python-poetry.org/), or any Python package manager.\n\n```text\n$ pipx install pyghidra-mcp\n$ pyghidra-mcp --help\n\nUsage: pyghidra-mcp [OPTIONS]\n\n Entry point for the MCP server\n\n Supports both stdio and sse transports. For stdio, it will read from stdin\n and write to stdout. For sse, it will start an HTTP server on port 8000.\n\nOptions:\n -v, --version Show version and exit.\n -t, --transport [stdio|sse|streamable-http] Transport protocol to use (stdio, sse or streamable-http)\n -h, --help Show this message and exit.\n```\n\n### Mapping Binaries with Docker\n\nWhen 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.\n\n```bash\n# Create and populate the new directory\nmkdir -p ./binaries\ncp /path/to/your/binaries/* ./binaries/\n\n# Run the Docker container with volume mapping\ndocker run -i --rm \\\n -v \"$(pwd)/binaries:/binaries\" \\\n ghcr.io/clearbluejar/pyghidra-mcp \\\n /binaries/*\n```\n\n### Using with OpenWeb-UI and MCPO\n\nYou can integrate `pyghidra-mcp` with [OpenWeb-UI](https://github.com/open-webui/open-webui) using [MCPO](https://github.com/open-webui/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.\n\n\nhttps://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95\n\n\n#### With `uvx`\n\nYou can run `pyghidra-mcp` and `mcpo` together using `uvx`:\n\n```bash\nuvx mcpo -- \\\n pyghidra-mcp /bin/ls\n```\n\n#### With Docker\n\nYou can combine mcpo with Docker:\n\n```bash\nuvx mcpo -- docker run ghcr.io/clearbluejar/pyghidra-mcp /bin/ls\n```\n\n### Standard Input/Output (stdio)\n\nThe stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools. See the [spec](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) for more details.\n\n#### Python\n\n```bash\npyghidra-mcp\n```\n\nBy 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.\n\n#### Docker\n\nThis server is published to Github's Container Registry ([ghcr.io/clearbluejar/pyghidra-mcp](http://ghcr.io/clearbluejar/pyghidra-mcp))\n\n```\ndocker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio\n```\n\nBy 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](https://docs.docker.com/reference/cli/docker/container/run/#interactive) mode.\n\n### Streamable HTTP\n\nStreamable HTTP enables streaming responses over JSON RPC via HTTP POST requests. See the [spec](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) for more details.\n\nBy default, the server listens on [127.0.0.1:8000/mcp](https://127.0.0.1/mcp) for client connections. To change any of this, set [FASTMCP_*](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/server.py#L78) environment variables. _The server must be running for clients to connect to it._\n\n#### Python\n\n```bash\npyghidra-mcp -t streamable-http\n```\n\nBy default, the Python package will run in `stdio` mode, so you will have to include `-t streamable-http`.\n\n#### Docker\n\n```\ndocker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp\n```\n\n### Server-sent events (SSE)\n\n> [!WARNING]\n> The MCP communiity considers this a legacy transport portcol and is really intended for backwards compatibility. [Streamable HTTP](#streamable-http) is the recommended replacement.\n\nSSE transport enables server-to-client streaming with Server-Send Events for client-to-server and server-to-client communication. See the [spec](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) for more details.\n\nBy default, the server listens on [127.0.0.1:8000/sse](https://127.0.0.1/sse) for client connections. To change any of this, set [FASTMCP_*](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/server.py#L78) environment variables. _The server must be running for clients to connect to it._\n\n#### Python\n\n```bash\npyghidra-mcp -t sse\n```\n\nBy default, the Python package will run in `stdio` mode, so you will have to include `-t sse`.\n\n#### Docker\n\n```\ndocker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse\n```\n\n## Integrations\n\n> [!NOTE]\n> This section is a work in progress. We will be adding examples for specific integrations soon.\n\n### Claude Desktop\n\nAdd the following JSON block to your `claude_desktop_config.json` file:\n\n```json\n{\n \"mcpServers\": {\n \"pyghidra-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"pyghidra-mcp\", \"/bin/ls\", \"/bin/jq\", \"/path/to/bin\" ],\n \"env\": {\n \"GHIDRA_INSTALL_DIR\": \"/path/to/ghidra\"\n }\n }\n }\n}\n```\n## Inspiration\n\nThis project implementation and design was inspired by these awesome projects:\n\n* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)\n* [semgrep-mcp](https://github.com/semgrep/mcp)\n* [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)\n* [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)\n\n## Contributing, community, and running from source\n\nWe believe the future of reverse engineering is agentic, contextual, and scalable.\n`pyghidra-mcp` is a step toward that future\u2014making full Ghidra projects accessible to AI agents and automation pipelines.\n\nWe\u2019re actively developing the project and welcome feedback, issues, and contributions.\n\n> [!NOTE]\n> We love your feedback, bug reports, feature requests, and code.\n______________________________________________________________________\n\nMade with \u2764\ufe0f by the [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Command-Line Ghidra MCP",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"dynamic-analysis",
" ghidra",
" mcp",
" pyghidra",
" reverse-engineering",
" security",
" static-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "93df780afb7d0243753fcd6afde769e9a276addbf71ef10e78295b3ad7520b4f",
"md5": "c615e5ffe70954076b0f3fd8cd479046",
"sha256": "f90098b0985c4886f6badb58c49403bdb961456a211b80e45ddd1b17d13ceb5d"
},
"downloads": -1,
"filename": "pyghidra_mcp-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c615e5ffe70954076b0f3fd8cd479046",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27439,
"upload_time": "2025-09-11T04:21:54",
"upload_time_iso_8601": "2025-09-11T04:21:54.256576Z",
"url": "https://files.pythonhosted.org/packages/93/df/780afb7d0243753fcd6afde769e9a276addbf71ef10e78295b3ad7520b4f/pyghidra_mcp-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9677c23f6e4f44ca53755db4bc86efd39835d9f87ba0028ca8738d706778cf8a",
"md5": "ad63b9128e8113664aca9edc2ea94374",
"sha256": "66301420c694c9dc56af8465319db4f3293b4e5d264e144f939d15b02fa8888a"
},
"downloads": -1,
"filename": "pyghidra_mcp-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "ad63b9128e8113664aca9edc2ea94374",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26432,
"upload_time": "2025-09-11T04:21:55",
"upload_time_iso_8601": "2025-09-11T04:21:55.532819Z",
"url": "https://files.pythonhosted.org/packages/96/77/c23f6e4f44ca53755db4bc86efd39835d9f87ba0028ca8738d706778cf8a/pyghidra_mcp-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 04:21:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyghidra-mcp"
}
JSON