Skip to content
Back to search

pyghidra-mcp

Python Command-Line Ghidra MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/clearbluejar--pyghidra-mcp/badge.svg)](/listings/clearbluejar--pyghidra-mcp)

HTML

<a href="/listings/clearbluejar--pyghidra-mcp"><img src="/api/listings/clearbluejar--pyghidra-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

How the Pieces Connect

flowchart LR
    subgraph Clients["Clients"]
        Agent["MCP host / agent"]
        Cli["pyghidra-mcp-cli"]
        User["Ghidra user"]
    end

    subgraph Process["pyghidra-mcp process"]
        Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
        Tools["MCP tools"]
        Context["PyGhidra context"]
    end

    Project["Ghidra project<br/>.gpr / .rep"]
    Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
    Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]

    Agent -->|"HTTP (recommended)"| Transport
    Cli -->|"HTTP only"| Transport
    Transport --> Tools
    Tools --> Context
    Context --> Project
    Context --> Artifacts
    Context -.-> Gui
    User -.-> Gui
    Gui -.-> Project

Choosing a Mode

flowchart TD
    Start["What do you need?"]
    Start --> Headless["Agent or automation"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Http["pyghidra-mcp<br/>--transport streamable-http"]
    GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
    Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
    HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]

- **Headless MCP**: use `streamable-http`. It keeps Ghidra and its project alive as one long-running server and works with both MCP hosts and the CLI client. - **GUI mode**: `pyghidra-mcp` launches Ghidra, opens the project, and exposes extra tools that steer the CodeBrowser in the same JVM. - **CLI client**: `pyghidra-mcp-cli` is an HTTP client. Start a `streamable-http` server first, then issue terminal commands against that running server. - **stdio**: retain this only for MCP hosts that cannot connect to an HTTP endpoint.

<details> <summary>Detailed architecture and tool surface</summary>

flowchart TD
    subgraph Clients
        Agent["LLM / MCP host"]
        Cli["pyghidra-mcp-cli"]
        Automation["scripts and CI"]
    end

    subgraph Transports
        Stdio["stdio"]
        Http["streamable-http"]
        Sse["sse legacy"]
    end

    subgraph Server["pyghidra-mcp server"]
        FastMcp["FastMCP tool server"]
        Context["PyGhidra context"]
        Indexing["background analysis and Chroma indexing"]

        subgraph Tools["MCP tools"]
            Analysis["decompile, xrefs, bytes, callgraph"]
            Search["symbols, strings, code"]
            ProjectOps["import, delete, metadata, list binaries"]
            Edits["rename function, rename variable, set type, set prototype, set comment"]
            GuiOnly["GUI only: open program, goto, list open programs, set current program"]
        end
    end

    subgraph GhidraRuntime["Ghidra runtime"]
        PyGhidra["pyghidra"]
        Jpype["JPype shared JVM"]
        Project["Ghidra project"]
        Programs["program databases"]
        CodeBrowser["Ghidra GUI / CodeBrowser"]
    end

    Agent --> Http
    Automation --> Http
    Automation --> Sse
    Cli --> Http

    Stdio --> FastMcp
    Http --> FastMcp
    Sse --> FastMcp

    FastMcp --> Context
    Context --> PyGhidra
    PyGhidra --> Jpype
    Jpype --> Project
    Project --> Programs
    Context --> Indexing
    Indexing --> Search

    FastMcp --> Tools
    Tools --> Context
    GuiOnly -.-> CodeBrowser
    Context -.-> CodeBrowser

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 798 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://github.com/user-attachments/assets/31c1831a-5be1-4698-8171-5ebfc9d6797c" width=60% >
  3. </p>
  4. <p align="center">
  5. <img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
  6. <img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
  7. <img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
  8. </p>
  9. # PyGhidra-MCP - Ghidra Model Context Protocol Server
  10. ### Overview
  11. **`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.
  12. 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.
  13. 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.
  14. 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.
  15. `pyghidra-mcp` now supports two operating modes:
  16. - `headless` mode for CLI-driven analysis and automation
  17. - `--gui` mode, which launches Ghidra through `pyghidra-mcp` and shares live program state with the running GUI
  18. > [!NOTE]
  19. > This beta project is under active development. We would love your feedback, bug reports, feature requests, and code.
  20. ## Yet another Ghidra MCP?
  21. Yes, the original [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) is fantastic. But `pyghidra-mcp` takes a different approach:
  22. - 🐍 **Headless-first, GUI-capable** – Run entirely via CLI for streamlined automation, or launch Ghidra with `--gui` when you want live GUI navigation and edits.
  23. - 🔁 **Designed for automation** – Ideal for integrating with LLMs, CI pipelines, and tooling that needs repeatable behavior.
  24. - ✅ **CI/CD friendly** – Built with robust unit and integration tests for both client and server sessions.
  25. - 🚀 **Quick startup** – Asynchronous startup allows the server to start handling requests while binaries are still being analyzed in the background. Supports fast command-line launching with minimal setup.
  26. - 📦 **Project-wide analysis** – Enables concurrent reverse engineering of all binaries in a Ghidra project
  27. - 🤖 **Agent-ready** – Built for intelligent agent-driven workflows and large-scale reverse engineering automation.
  28. - 🔍 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.
  29. This project provides a Python-first experience optimized for local development, headless environments, and testable workflows.
  30. ## Setup Diagrams
  31. ### How the Pieces Connect
  32. ```mermaid
  33. flowchart LR
  34. subgraph Clients["Clients"]
  35. Agent["MCP host / agent"]
  36. Cli["pyghidra-mcp-cli"]
  37. User["Ghidra user"]
  38. end
  39. subgraph Process["pyghidra-mcp process"]
  40. Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
  41. Tools["MCP tools"]
  42. Context["PyGhidra context"]
  43. end
  44. Project["Ghidra project<br/>.gpr / .rep"]
  45. Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
  46. Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]
  47. Agent -->|"HTTP (recommended)"| Transport
  48. Cli -->|"HTTP only"| Transport
  49. Transport --> Tools
  50. Tools --> Context
  51. Context --> Project
  52. Context --> Artifacts
  53. Context -.-> Gui
  54. User -.-> Gui
  55. Gui -.-> Project
  56. ```
  57. ### Choosing a Mode
  58. ```mermaid
  59. flowchart TD
  60. Start["What do you need?"]
  61. Start --> Headless["Agent or automation"]
  62. Start --> GuiNeed["Live Ghidra GUI control"]
  63. Start --> Terminal["Interactive terminal client"]
  64. Headless --> Http["pyghidra-mcp<br/>--transport streamable-http"]
  65. GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
  66. Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
  67. HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]
  68. ```
  69. - **Headless MCP**: use `streamable-http`. It keeps Ghidra and its project alive as one long-running server and works with both MCP hosts and the CLI client.
  70. - **GUI mode**: `pyghidra-mcp` launches Ghidra, opens the project, and exposes extra tools that steer the CodeBrowser in the same JVM.
  71. - **CLI client**: `pyghidra-mcp-cli` is an HTTP client. Start a `streamable-http` server first, then issue terminal commands against that running server.
  72. - **stdio**: retain this only for MCP hosts that cannot connect to an HTTP endpoint.
  73. <details>
  74. <summary>Detailed architecture and tool surface</summary>
  75. ```mermaid
  76. flowchart TD
  77. subgraph Clients
  78. Agent["LLM / MCP host"]
  79. Cli["pyghidra-mcp-cli"]
  80. Automation["scripts and CI"]
  81. end
  82. subgraph Transports
  83. Stdio["stdio"]
  84. Http["streamable-http"]
  85. Sse["sse legacy"]
  86. end
  87. subgraph Server["pyghidra-mcp server"]
  88. McpServer["MCPServer tool server"]
  89. Context["PyGhidra context"]
  90. Indexing["background analysis and Chroma indexing"]
  91. subgraph Tools["MCP tools"]
  92. Analysis["decompile, xrefs, bytes, callgraph"]
  93. Search["symbols, strings, code"]
  94. ProjectOps["import, delete, metadata, list binaries"]
  95. Edits["rename function, rename variable, set type, set prototype, set comment"]
  96. GuiOnly["GUI only: open program, goto, list open programs, set current program"]
  97. end
  98. end
  99. subgraph GhidraRuntime["Ghidra runtime"]
  100. PyGhidra["pyghidra"]
  101. Jpype["JPype shared JVM"]
  102. Project["Ghidra project"]
  103. Programs["program databases"]
  104. CodeBrowser["Ghidra GUI / CodeBrowser"]
  105. end
  106. Agent --> Http
  107. Automation --> Http
  108. Automation --> Sse
  109. Cli --> Http
  110. Stdio --> McpServer
  111. Http --> McpServer
  112. Sse --> McpServer
  113. McpServer --> Context
  114. Context --> PyGhidra
  115. PyGhidra --> Jpype
  116. Jpype --> Project
  117. Project --> Programs
  118. Context --> Indexing
  119. Indexing --> Search
  120. McpServer --> Tools
  121. Tools --> Context
  122. GuiOnly -.-> CodeBrowser
  123. Context -.-> CodeBrowser
  124. ```
  125. </details>
  126. ## Contents
  127. - [PyGhidra-MCP - Ghidra Model Context Protocol Server](#pyghidra-mcp---ghidra-model-context-protocol-server)
  128. - [Overview](#overview)
  129. - [Yet another Ghidra MCP?](#yet-another-ghidra-mcp)
  130. - [Setup Diagrams](#setup-diagrams)
  131. - [How the Pieces Connect](#how-the-pieces-connect)
  132. - [Choosing a Mode](#choosing-a-mode)
  133. - [Contents](#contents)
  134. - [Getting started](#getting-started)
  135. - [Optimized for Agents](#optimized-for-agents)
  136. - [CLI Client](#cli-client)
  137. - [Installation](#installation)
  138. - [Quick Start with CLI](#quick-start-with-cli)
  139. - [Project Creation, Management, and Opening Existing Projects](#project-creation-management-and-opening-existing-projects)
  140. - [Creating New Projects](#creating-new-projects)
  141. - [Self-Contained Project Structure](#self-contained-project-structure)
  142. - [Basic Project Creation](#basic-project-creation)
  143. - [Custom Project Creation](#custom-project-creation)
  144. - [Creating Multiple Related Projects](#creating-multiple-related-projects)
  145. - [Opening Existing Ghidra Projects](#opening-existing-ghidra-projects)
  146. - [Opening by .gpr File](#opening-by-gpr-file)
  147. - [GUI Mode](#gui-mode)
  148. - [Startup Defaults and Large Projects](#startup-defaults-and-large-projects)
  149. - [Development](#development)
  150. - [Setup](#setup)
  151. - [Testing and Quality](#testing-and-quality)
  152. - [API](#api)
  153. - [Tools](#tools)
  154. - [Batch Operations](#batch-operations)
  155. - [Read / Analysis Tools](#read--analysis-tools)
  156. - [Project Operations](#project-operations)
  157. - [Edit / Mutation Tools](#edit--mutation-tools)
  158. - [GUI Control Tools (`--gui` only)](#gui-control-tools---gui-only)
  159. - [Usage](#usage)
  160. - [Mapping Binaries with Docker](#mapping-binaries-with-docker)
  161. - [Streamable HTTP](#streamable-http)
  162. - [Python](#python)
  163. - [Docker](#docker)
  164. - [Claude Code](#claude-code)
  165. - [Codex](#codex)
  166. - [Standard Input/Output (stdio)](#standard-inputoutput-stdio)
  167. - [Python](#python-1)
  168. - [Docker](#docker-1)
  169. - [Using with OpenWeb-UI and MCPO](#using-with-openweb-ui-and-mcpo)
  170. - [With `uvx`](#with-uvx)
  171. - [With Docker](#docker-2)
  172. - [Server-sent events (SSE)](#server-sent-events-sse)
  173. - [Python](#python-2)
  174. - [Docker](#docker-3)
  175. - [Inspiration](#inspiration)
  176. - [Contributing, community, and running from source](#contributing-community-and-running-from-source)
  177. - [Contributor workflow](#contributor-workflow)
  178. ## Getting started
  179. Start a persistent Streamable HTTP server using the [Python package](https://pypi.org/p/pyghidra-mcp) and [`uv`](https://docs.astral.sh/uv/guides/tools/):
  180. ```bash
  181. uvx pyghidra-mcp \
  182. --transport streamable-http \
  183. --project-path /absolute/path/to/ghidra-projects \
  184. /absolute/path/to/binary
  185. ```
  186. The server is then available at `http://127.0.0.1:8000/mcp`. Leave it running and configure your MCP client to use that URL; the [Claude Code](#claude-code) and [Codex](#codex) examples below show the expected configuration.
  187. To launch and control a live Ghidra GUI from MCP, use `--gui` with `streamable-http`:
  188. ```bash
  189. uvx pyghidra-mcp \
  190. --gui \
  191. --transport streamable-http \
  192. --host 127.0.0.1 \
  193. --port 8000 \
  194. --project-path /absolute/path/to/ghidra-projects \
  195. --project-name my_project
  196. ```
  197. > [!IMPORTANT]
  198. > `--gui` launches Ghidra through `pyghidra-mcp`. It does not attach to an already-running external Ghidra instance.
  199. Or, run as a [Docker container](https://ghcr.io/clearbluejar/pyghidra-mcp):
  200. ```bash
  201. docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
  202. ```
  203. ## Optimized for Agents
  204. `pyghidra-mcp` keeps the MCP surface intentionally narrow so agent clients spend fewer tokens on tool discovery and argument selection.
  205. - **Short tool descriptions**: MCP tool docstrings are kept compact so MCPServer tool schemas stay small and cheap to send to models.
  206. - **Context discipline**: tools return focused structured data instead of dumping whole-program context by default. Decompilation, symbol search, and cross-reference results are shaped to support iterative analysis rather than one large response.
  207. - **GUI tools only when relevant**: GUI-only controls such as `open_program_in_gui`, `list_open_programs`, `set_current_program`, and `goto` are only exposed when the server is started with `--gui`.
  208. - **CLI is optional**: if MCP is not your preferred interface, `pyghidra-mcp-cli` provides a direct command-line client over HTTP with grouped commands for common edit and analysis workflows.
  209. This keeps the default server usable for LLM agents, IDE integrations, and automation without exposing unnecessary tool surface or GUI-only controls in headless sessions.
  210. ## CLI Client
  211. For a more interactive command-line experience, you can use the separate **pyghidra-mcp-cli** package, which provides a user-friendly interface for interacting with a running pyghidra-mcp server.
  212. ### Installation
  213. Install the CLI client using [`uv`](https://docs.astral.sh/uv/) (recommended):
  214. ```bash
  215. uvx pyghidra-mcp-cli
  216. ```
  217. Or install with pip:
  218. ```bash
  219. pip install pyghidra-mcp-cli
  220. ```
  221. ### Quick Start with CLI
  222. 1. **Start the server** (in one terminal):
  223. ```bash
  224. pyghidra-mcp --transport streamable-http /bin/ls
  225. ```
  226. 2. **Use the CLI** (in another terminal):
  227. ```bash
  228. # List available binaries
  229. pyghidra-mcp-cli list binaries
  230. # Decompile a function
  231. pyghidra-mcp-cli decompile --binary ls main
  232. # Decompile with callees, referenced strings, and cross-references
  233. pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs
  234. # Search for symbols (supports regex patterns)
  235. pyghidra-mcp-cli search symbols --binary ls printf -l 10
  236. ```
  237. > [!NOTE]
  238. > The CLI connects to pyghidra-mcp via HTTP to avoid the 10-60 second startup overhead of spawning a new Ghidra process for each command. See the [CLI README](./cli/README.md) for complete documentation.
  239. ## Project Creation, Management, and Opening Existing Projects
  240. ### MCP Python SDK compatibility
  241. The server and optional CLI support `mcp>=1.26.0,<3`. Install the same packages
  242. with either SDK major; no SDK-specific edition or runtime flag is required.
  243. The server selects SDK 1's `FastMCP` or SDK 2's `MCPServer` from the installed
  244. dependency, and the CLI accepts both HTTP transport return formats.
  245. Fresh installations normally resolve to the latest compatible SDK. To keep an
  246. existing SDK 1 environment, install with an explicit constraint:
  247. ```bash
  248. pip install pyghidra-mcp 'mcp>=1.26.0,<2'
  249. ```
  250. Python SDK versions are separate from the MCP protocol versions negotiated by
  251. clients and servers.
  252. ### Creating New Projects
  253. You can create new projects in several ways, depending on your workflow:
  254. #### Self-Contained Project Structure
  255. `pyghidra-mcp` creates a **self-contained project structure** where each project has its own Ghidra project and pyghidra-mcp artifacts. This ensures complete isolation and easy project management.
  256. #### Basic Project Creation
  257. ```bash
  258. # Create a new project with default settings
  259. pyghidra-mcp
  260. # Creates:
  261. $ tree pyghidra_mcp_projects/
  262. pyghidra_mcp_projects/
  263. ├── my_project.gpr
  264. ├── my_project-pyghidra-mcp
  265. │ ├── chromadb
  266. │ └── gzfs
  267. └── my_project.rep
  268. ```
  269. #### Custom Project Creation
  270. ```bash
  271. # Create project with custom name and location
  272. pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis
  273. $ tree ~/analysis/
  274. /home/vscode/analysis/
  275. └── malware_study
  276. ├── malware_analysis.gpr
  277. ├── malware_analysis-pyghidra-mcp
  278. │ ├── chromadb
  279. │ └── gzfs
  280. └── malware_analysis.rep
  281. ```
  282. #### Creating Multiple Related Projects
  283. ```bash
  284. # Create separate projects for different analysis focuses
  285. mkdir ~/reverse_engineering_workspace
  286. # Project for suspicious binaries
  287. pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
  288. # Project for packed malware
  289. pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis
  290. ```
  291. ### Opening Existing Ghidra Projects
  292. If you have existing Ghidra projects (`.gpr` files), you can open them directly with `pyghidra-mcp`:
  293. #### Opening by .gpr File
  294. ```bash
  295. # Open existing Ghidra project (project name derived from filename)
  296. pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr
  297. # Result: ~/existing/ghidra/my_research-pyghidra-mcp/
  298. # └── chromadb/, gzfs/ (pyghidra-mcp additions)
  299. ```
  300. ### GUI Mode
  301. Use GUI mode when you want MCP actions to operate against the same live program objects that Ghidra is displaying.
  302. - `--gui` requires `--transport streamable-http` (or `--transport http` as an alias)
  303. - `--project-path` can be a project directory plus `--project-name`, or an existing `.gpr` file. Missing projects are created automatically.
  304. - Ghidra is launched by `pyghidra-mcp`, which keeps GUI and MCP transactions in the same JVM
  305. - GUI-only tools are only exposed when running with `--gui`
  306. Example:
  307. ```bash
  308. pyghidra-mcp \
  309. --gui \
  310. --transport streamable-http \
  311. --project-path /absolute/path/to/my_research.gpr
  312. ```
  313. GUI mode is the right choice when you want to:
  314. - open or switch programs in CodeBrowser
  315. - navigate the listing to a function or address
  316. - rename functions or add comments and immediately see those changes in Ghidra
  317. ### Startup Defaults and Large Projects
  318. `pyghidra-mcp` does not require `--wait-for-analysis` by default. The server can start while analysis and MCP-side indexing continue in the background.
  319. This matters for large projects:
  320. - starting a project with many binaries does not need to block server startup
  321. - `--wait-for-analysis` is available when you want a fully analyzed project before serving requests
  322. - for large existing projects, expect analysis and indexing readiness to vary by binary
  323. Current limitation:
  324. - Ghidra analysis state and MCP indexing state are separate
  325. - a binary can be fully analyzed in Ghidra while `search_strings` or semantic `search_code` are still waiting on MCP-side indexing
  326. - this is more noticeable when opening larger existing projects
  327. In practice:
  328. - decompilation, navigation, renaming, and comments can still work for a binary while indexing-heavy search features are catching up
  329. - if startup latency matters more than immediate search readiness, keep the default `--no-wait-for-analysis`
  330. - if immediate readiness matters more than startup time, use `--wait-for-analysis`
  331. ## Development
  332. 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.
  333. ### Setup
  334. 1. **Install `uv`**: If you don't have `uv` installed, you can install it using pip:
  335. ```bash
  336. pip install uv
  337. ```
  338. Or, follow the official `uv` installation guide: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
  339. 2. **Create a virtual environment and install dependencies**:
  340. ```bash
  341. make dev-setup
  342. source ./.venv/bin/activate
  343. ```
  344. 3. **Set Ghidra Environment Variable**: Download and install Ghidra, then set the `GHIDRA_INSTALL_DIR` environment variable to your Ghidra installation directory.
  345. ```bash
  346. # For Linux / Mac
  347. export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
  348. # For Windows PowerShell
  349. [System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\path\to\ghidra')
  350. ```
  351. ### Testing and Quality
  352. The `Makefile` provides several targets for testing and code quality:
  353. - `make run`: Run the MCP server.
  354. - `make test`: Run the full test suite (unit and integration).
  355. - `make test-unit`: Run unit tests.
  356. - `make test-integration`: Run integration tests.
  357. - `make test-integration-fast`: Run the lightweight integration smoke test used by pre-commit.
  358. - `make test-integration-gui`: Run GUI integration tests. Requires a working Ghidra install and GUI support.
  359. - `make lint`: Check code style with `ruff`.
  360. - `make format`: Format code with `ruff`.
  361. - `make typecheck`: Run lightweight static checks with `ruff`.
  362. - `make check`: Run all quality checks.
  363. - `make dev`: Run the development workflow (format and check).
  364. - `make build`: Build distribution packages.
  365. - `make clean`: Clean build artifacts and cache.
  366. Recommended split:
  367. - pre-commit: `ruff`, `pyright`, unit tests, and one lightweight integration smoke test
  368. - GitHub Actions: full Linux headless integration coverage, Linux GUI under `Xvfb`, CLI coverage, and current macOS smoke tests
  369. - scheduled CI: older macOS / Ghidra compatibility coverage
  370. - local/manual: heavier environment-specific GUI debugging and release sanity checks
  371. ## API
  372. ### Tools
  373. Enable LLMs to perform actions, make deterministic computations, and interact with external services.
  374. #### Batch Operations
  375. `decompile_function` and `list_xrefs` accept a single target or a list of targets, reducing round-trips when analyzing call chains or multiple symbols at once.
  376. ```jsonc
  377. // Decompile three functions in one call, with callees and xrefs attached
  378. {
  379. "binary_name": "firmware.bin",
  380. "name_or_address": ["main", "init_hardware", "0x08001234"],
  381. "include_callees": true,
  382. "include_xrefs": true
  383. }
  384. // Get cross-references for multiple symbols at once
  385. {
  386. "binary_name": "firmware.bin",
  387. "name_or_address": ["malloc", "free", "realloc"]
  388. }
  389. ```
  390. Per-item errors are returned inline (other targets still succeed):
  391. ```jsonc
  392. [
  393. {"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
  394. {"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
  395. ]
  396. ```
  397. #### Read / Analysis Tools
  398. - `search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0)`: Search decompiled pseudo-C using semantic vector search or literal matching.
  399. - `list_xrefs(binary_name: str, name_or_address: str | list[str])`: List cross-references to function(s), symbol(s), or address(es). Accepts a single target or a list for batch lookup.
  400. - `gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120)`: Generates a MermaidJS call graph for a specified function. Supports both "calling" (functions called by the target) and "called" (functions that call the target) directions with multiple visualization types.
  401. - `decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30)`: Decompile function(s) by name or address. Accepts a single target or a list for batch decompilation. Rich response flags attach callees, strings, and/or xrefs to each result. `timeout_sec` applies per target and bounds each decompilation attempt independently.
  402. - `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lists all exported functions and symbols from a specified binary (regex supported for query).
  403. - `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lists all imported functions and symbols for a specified binary (regex supported for query).
  404. - `read_bytes(binary_name: str, address: str, size: int = 32)`: Reads raw bytes from memory at a specified address. Hex addresses may include or omit the `0x` prefix.
  405. - `search_strings(binary_name: str, query: str, limit: int = 100)`: Searches strings within a binary.
  406. - `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Search for symbols within a binary by name. Supports regex patterns (e.g. `^main$`, `func.*one`) with case-insensitive matching, or plain substring queries. Set `functions_only=True` to exclude labels, variables, and other non-function symbols.
  407. #### Project Operations
  408. - `import_binary(binary_path: str)`: Imports a binary from a designated path into the current Ghidra project. If the path is a directory, it will recursively scan and import all supported binary files, preserving the directory structure within the Ghidra project.
  409. - `list_project_binaries()`: Lists binaries in the current Ghidra project. In GUI mode this includes project binaries that exist on disk even if they are not currently open in CodeBrowser.
  410. - `list_project_binary_metadata(binary_name: str)`: Retrieves detailed metadata for a specific binary, including architecture, compiler, executable format, analysis metrics, and file hashes.
  411. - `delete_project_binary(binary_name: str)`: Deletes a binary (program) from the Ghidra project.
  412. #### Edit / Mutation Tools
  413. - `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Rename a function by name or address. In GUI mode this runs as a live Ghidra transaction and updates the open program.
  414. - `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Rename a function parameter or local variable by exact name within a specific function. If the name is missing or ambiguous within that function, the tool returns an error instead of guessing. In GUI mode this runs as a live Ghidra transaction and updates the open program.
  415. - `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Set the data type for a function parameter or local variable by exact name within a specific function. If the name is missing or ambiguous within that function, the tool returns an error instead of guessing. `type_name` is parsed using Ghidra's datatype parser against the program datatype manager.
  416. - `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Set a function prototype from a full signature string. The tool always runs the prototype through Ghidra's native signature parser and returns the underlying parser or apply error if the prototype is invalid.
  417. - `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Set a function/decompiler comment or listing comment. Listing comment targets can be addresses, symbols, or functions. Supported `comment_type` values are `decompiler`, `plate`, `pre`, `eol`, `post`, and `repeatable`.
  418. #### GUI Control Tools (`--gui` only)
  419. These tools are only available when `pyghidra-mcp` is started with `--gui` and control what the GUI is showing rather than mutating project data directly:
  420. - `list_open_programs()`: List programs currently open in the Ghidra GUI.
  421. - `open_program_in_gui(binary_name: str, new_window: bool = True)`: Open a project binary in CodeBrowser. By default this opens a new CodeBrowser window. Set `new_window=false` to reuse a visible CodeBrowser when possible.
  422. - `set_current_program(binary_name: str)`: Make an open program the active/current program in the primary GUI tool context.
  423. - `goto(binary_name: str, target: str, target_type: str)`: Navigate the Ghidra GUI to an address or function. `target_type` must be `address` or `function`.
  424. ## Usage
  425. 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.
  426. ```text
  427. $ uvx pyghidra-mcp --help
  428. Usage: pyghidra-mcp [OPTIONS] [INPUT_PATHS]...
  429. PyGhidra Command-Line MCP server
  430. Options:
  431. -v, --version Show version and exit.
  432. -t, --transport [stdio|streamable-http|sse|http]
  433. Transport protocol. SSE is deprecated;
  434. use streamable-http instead. [default: stdio]
  435. -p, --port INTEGER Port for HTTP-based transports. [default: 8000]
  436. -o, --host TEXT Host for HTTP-based transports. [default: 127.0.0.1]
  437. --project-path PATH Directory for a pyghidra-mcp project or an
  438. existing Ghidra .gpr file. [default: pyghidra_mcp_projects]
  439. --project-name TEXT Ghidra project name. Ignored for .gpr paths.
  440. [default: my_project]
  441. --threaded / --no-threaded Allow threaded analysis. [default: threaded]
  442. --max-workers INTEGER Number of analysis workers; 0 means CPU count.
  443. [default: 0]
  444. --wait-for-analysis / --no-wait-for-analysis
  445. Wait for initial analysis before starting.
  446. [default: no-wait-for-analysis]
  447. --gui / --no-gui Launch Ghidra GUI in-process and serve MCP
  448. against GUI-open programs. Cannot attach to
  449. an already-running external Ghidra process.
  450. [default: no-gui]
  451. --list-project-binaries List ingested project binaries and exit.
  452. --delete-project-binary TEXT Delete a project binary by name and exit.
  453. --force-analysis / --no-force-analysis
  454. Force a new binary analysis each run.
  455. [default: no-force-analysis]
  456. --verbose-analysis / --no-verbose-analysis
  457. Verbose logging for analysis. [default: no-verbose-analysis]
  458. --no-symbols / --with-symbols Turn off symbols for analysis. [default: with-symbols]
  459. --sym-file-path PATH Single PDB symbol file for one binary.
  460. -s, --symbols-path PATH Local symbols directory.
  461. --gdt PATH Path to GDT files. May be specified multiple times.
  462. --program-options PATH JSON file with Ghidra program options.
  463. --gzfs-path PATH Location to store GZFs of analyzed binaries.
  464. -h, --help Show this message and exit.
  465. ```
  466. ### Mapping Binaries with Docker
  467. 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.
  468. ```bash
  469. # Create and populate the new directory
  470. mkdir -p ./binaries
  471. cp /path/to/your/binaries/* ./binaries/
  472. # Run the Docker container with volume mapping
  473. docker run -i --rm \
  474. -v "$(pwd)/binaries:/binaries" \
  475. ghcr.io/clearbluejar/pyghidra-mcp \
  476. /binaries/*
  477. ```
  478. ### Streamable HTTP
  479. Streamable HTTP is the recommended transport. It keeps one Ghidra process and project available to MCP hosts and `pyghidra-mcp-cli`, avoiding the startup cost of a separate process per client. It sends JSON-RPC requests over HTTP; see the [spec](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) for details.
  480. By default, the server listens on [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) for client connections. Use `--host` / `--port` or the `MCP_HOST` / `MCP_PORT` environment variables to change the bind address. _The server must be running for clients to connect to it._
  481. #### Python
  482. ```bash
  483. pyghidra-mcp -t streamable-http
  484. ```
  485. The Python package defaults to `stdio`, so always include `--transport streamable-http` when starting the server.
  486. GUI mode uses this transport:
  487. ```bash
  488. pyghidra-mcp \
  489. --gui \
  490. --transport streamable-http \
  491. --project-path /absolute/path/to/my_project.gpr
  492. ```
  493. #### Docker
  494. ```
  495. docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
  496. ```
  497. ### Claude Code
  498. After starting the HTTP server, add it to Claude Code:
  499. ```bash
  500. claude mcp add --transport http pyghidra-mcp http://127.0.0.1:8000/mcp
  501. ```
  502. For a project-shared configuration, add this to `.mcp.json` in the project root:
  503. ```json
  504. {
  505. "mcpServers": {
  506. "pyghidra-mcp": {
  507. "type": "http",
  508. "url": "http://127.0.0.1:8000/mcp"
  509. }
  510. }
  511. }
  512. ```
  513. `type: "http"` is required: an entry with only `url` is treated as a stdio server by Claude Code. Use `claude mcp list` or `/mcp` to verify the connection.
  514. ### Codex
  515. After starting the HTTP server, add the following to `~/.codex/config.toml`:
  516. ```toml
  517. [mcp_servers.pyghidra-mcp]
  518. url = "http://127.0.0.1:8000/mcp"
  519. ```
  520. Restart Codex after saving the configuration. The server name is arbitrary; `pyghidra-mcp` is the name that will appear in Codex.
  521. ### Standard Input/Output (stdio)
  522. Use stdio only when an MCP host cannot use an HTTP endpoint. It starts a server that communicates over its parent process's standard input and output streams.
  523. #### Python
  524. ```bash
  525. pyghidra-mcp --transport stdio
  526. ```
  527. Because the server communicates on standard input and output, it will appear to wait without terminal output; that is expected.
  528. #### Docker
  529. ```bash
  530. docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio
  531. ```
  532. The Docker image starts the Streamable HTTP server by default, so include `-t stdio` after the image name and use `-i` for [interactive](https://docs.docker.com/reference/cli/docker/container/run/#interactive) stdio mode.
  533. ### Using with OpenWeb-UI and MCPO
  534. Use [MCPO](https://github.com/open-webui/mcpo) only when OpenWeb-UI or another consumer specifically requires an OpenAPI proxy. For normal MCP clients, connect directly to the Streamable HTTP endpoint above.
  535. https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95
  536. #### With `uvx`
  537. ```bash
  538. uvx mcpo -- pyghidra-mcp /bin/ls
  539. ```
  540. #### With Docker
  541. ```bash
  542. uvx mcpo -- docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp /bin/ls
  543. ```
  544. ### Server-sent events (SSE)
  545. > [!WARNING]
  546. > The MCP community considers this a legacy transport protocol intended for backwards compatibility. [Streamable HTTP](#streamable-http) is the recommended replacement.
  547. 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.
  548. By default, the server listens on [http://127.0.0.1:8000/sse](http://127.0.0.1:8000/sse) for client connections. Use `--host` / `--port` or the `MCP_HOST` / `MCP_PORT` environment variables to change the bind address. _The server must be running for clients to connect to it._
  549. #### Python
  550. ```bash
  551. pyghidra-mcp -t sse
  552. ```
  553. By default, the Python package will run in `stdio` mode, so you will have to include `-t sse`.
  554. #### Docker
  555. ```
  556. docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse
  557. ```
  558. ## Inspiration
  559. This project implementation and design was inspired by these awesome projects:
  560. * [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
  561. * [semgrep-mcp](https://github.com/semgrep/mcp)
  562. * [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)
  563. * [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)
  564. ---
  565. ## Contributing, community, and running from source
  566. We believe the future of reverse engineering is agentic, contextual, and scalable.
  567. `pyghidra-mcp` is a step toward that future—making full Ghidra projects accessible to AI agents and automation pipelines.
  568. We’re actively developing the project and welcome feedback, issues, and contributions.
  569. > [!NOTE]
  570. > We love your feedback, bug reports, feature requests, and code.
  571. ### Contributor workflow
  572. If you're adding a new tool or integration, here’s the recommended workflow:
  573. - Label your branch with the prefix `feature/` to indicate a new capability.
  574. - Add your tool using the same style and structure as existing tools in `pyghidra/tools/`.
  575. - Write an integration test that exercises your tool using a `StdioClient` instance. Place it in `tests/integration/`.
  576. - Extend concurrent testing by adding a call to your tool in `tests/integration/test_concurrent_streamable_client.py`.
  577. - Run make test and make format to ensure your changes pass all tests and conform to linting rules.
  578. This ensures consistency across the codebase and helps us maintain robust, scalable tooling for reverse engineering workflows.
  579. ______________________________________________________________________
  580. Made with ❤️ by the [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.