PyGhidra-MCP - Ghidra 模型上下文协议服务器

概述

pyghidra-mcp 是一个命令行模型上下文协议 (MCP) 服务器，它将 Ghidra（一款强大的软件逆向工程 (SRE) 套件）的全部分析能力引入智能代理和基于 LLM 的工具世界。它通过 pyghidra 和 jpype 将 Ghidra 的 ProgramAPI 和 FlatProgramAPI 桥接到 Python，然后通过模型上下文协议暴露这些功能。

MCP 是一个统一接口，允许语言模型、开发工具（如 VS Code）和自主代理访问结构化上下文、调用工具并进行智能协作。可以将 MCP 视为强大分析工具与 LLM 生态系统之间的桥梁。

使用 pyghidra-mcp，Ghidra 成为一个智能后端——随时准备响应上下文丰富的查询、自动化深度逆向工程任务，并集成到 AI 辅助工作流中。

pyghidra-mcp 现在支持两种操作模式：

headless 模式，用于 CLI 驱动的分析和自动化
--gui 模式，通过 pyghidra-mcp 启动 Ghidra 并与运行中的 GUI 共享实时程序状态

[!NOTE] 此 Beta 项目正在积极开发中。我们欢迎您的反馈、错误报告、功能请求和代码贡献。

又一个 Ghidra MCP？

是的，原版 ghidra-mcp 非常出色。但 pyghidra-mcp 采取了不同的方法：

🐍 首选无头模式，支持 GUI – 完全通过 CLI 运行以实现精简自动化，或在使用 --gui 启动 Ghidra 时进行实时 GUI 导航和编辑。
🔁 专为自动化设计 – 非常适合集成到 LLM、CI 管道和需要可重复行为的工具中。
✅ CI/CD 友好 – 包含针对客户端和服务器会话的强大单元测试和集成测试。
🚀 快速启动 – 异步启动允许服务器在处理请求的同时后台分析二进制文件。支持快速命令行启动，设置最小化。
📦 项目范围分析 – 支持并发逆向工程 Ghidra 项目中的所有二进制文件
🤖 代理就绪 – 为智能代理驱动的工作流和大规模逆向工程自动化而构建。
🔍 语义代码搜索 – 使用向量嵌入（通过 ChromaDB）实现对反编译函数、注释和符号的快速模糊查找——非常适合伪 C 代码探索和代理驱动的分类。

该项目提供以 Python 为先的体验，针对本地开发、无头环境和可测试工作流进行了优化。

设置图

各部分如何连接```mermaid

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

subgraph Process["pyghidra-mcp process"]
    Transport["stdio or streamable-http"]
    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 -->|"stdio or HTTP"| Transport
Cli -->|"HTTP only"| Transport
Transport --> Tools
Tools --> Context
Context --> Project
Context --> Artifacts
Context -.-> Gui
User -.-> Gui
Gui -.-> Project

### 选择模式```mermaid
flowchart TD
    Start["What do you need?"]
    Start --> Headless["Agent or automation only"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Stdio["pyghidra-mcp -t stdio<br/>or -t 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"]

无头 MCP：为本地 MCP 主机使用 stdio，或在多个客户端需要同一个长期运行的 Ghidra 项目时使用 streamable-http。
GUI 模式：pyghidra-mcp 启动 Ghidra、打开项目，并暴露额外的工具，用于在同一 JVM 中操控 CodeBrowser。
CLI 客户端：pyghidra-mcp-cli 是一个 HTTP 客户端。先启动一个 streamable-http 服务器，然后向该运行中的服务器发出终端命令。

详细架构及工具界面

```mermaid 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 --> Stdio
Agent --> Http
Automation --> Stdio
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>

## 目录

- [PyGhidra-MCP - Ghidra 模型上下文协议服务器](#pyghidra-mcp---ghidra-model-context-protocol-server)
    - [概述](#overview)
  - [又一个 Ghidra MCP？](#yet-another-ghidra-mcp)
  - [设置图](#setup-diagrams)
    - [各部分如何连接](#how-the-pieces-connect)
    - [选择模式](#choosing-a-mode)
  - [目录](#contents)
  - [开始使用](#getting-started)
  - [针对智能体优化](#optimized-for-agents)
  - [CLI 客户端](#cli-client)
    - [安装](#installation)
    - [CLI 快速开始](#quick-start-with-cli)
  - [项目创建、管理及打开现有项目](#project-creation-management-and-opening-existing-projects)
    - [创建新项目](#creating-new-projects)
      - [自包含项目结构](#self-contained-project-structure)
      - [基本项目创建](#basic-project-creation)
      - [自定义项目创建](#custom-project-creation)
      - [创建多个相关项目](#creating-multiple-related-projects)
    - [打开现有 Ghidra 项目](#opening-existing-ghidra-projects)
      - [通过 .gpr 文件打开](#opening-by-gpr-file)
    - [GUI 模式](#gui-mode)
    - [启动默认值和大项目](#startup-defaults-and-large-projects)
  - [开发](#development)
    - [设置](#setup)
    - [测试与质量](#testing-and-quality)
  - [API](#api)
    - [工具](#tools)
      - [批量操作](#batch-operations)
      - [读取/分析工具](#read--analysis-tools)
      - [项目操作](#project-operations)
      - [编辑/更改工具](#edit--mutation-tools)
      - [GUI 控制工具（仅 `--gui`）](#gui-control-tools---gui-only)
  - [用法](#usage)
    - [使用 Docker 映射二进制文件](#mapping-binaries-with-docker)
    - [与 OpenWeb-UI 和 MCPO 一起使用](#using-with-openweb-ui-and-mcpo)
      - [使用 `uvx`](#with-uvx)
      - [使用 Docker](#with-docker)
    - [标准输入/输出（stdio）](#standard-inputoutput-stdio)
      - [Python](#python)
      - [Docker](#docker)
    - [可流式 HTTP](#streamable-http)
      - [Python](#python-1)
      - [Docker](#docker-1)
    - [服务器发送事件（SSE）](#server-sent-events-sse)
      - [Python](#python-2)
      - [Docker](#docker-2)
  - [集成](#integrations)
    - [Claude Desktop](#claude-desktop)
  - [灵感](#inspiration)
  - [贡献、社区及从源码运行](#contributing-community-and-running-from-source)
    - [贡献者工作流](#contributor-workflow)

## 开始使用

使用 [`uv`](https://docs.astral.sh/uv/guides/tools/) 将 [Python 包](https://pypi.org/p/pyghidra-mcp) 作为 CLI 命令运行：```bash
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default

GUI模式是当你想在以下情况下选择的正确方式： - 在CodeBrowser中打开或切换程序 - 导航列表到函数或地址 - 重命名函数或添加注释，并立即在Ghidra中看到这些更改 ### 启动默认设置与大型项目 `pyghidra-mcp` 默认不需要 `--wait-for-analysis`。服务器可以在分析和MCP端索引在后台继续时启动。这对大型项目很重要： - 启动包含许多二进制文件的项目不需要阻塞服务器启动 - 当你希望在服务请求之前获得完全分析的项目时，可以使用 `--wait-for-analysis` - 对于大型现有项目，预计分析和索引就绪状态因二进制文件而异当前限制： - Ghidra分析状态和MCP索引状态是分开的 - 一个二进制文件在Ghidra中可能已经完全分析，而 `search_strings` 或语义 `search_code` 仍在等待MCP端索引 - 这在打开较大的现有项目时更为明显实际使用中： - 反编译、导航、重命名和注释仍然可以用于一个二进制文件，而索引密集型搜索功能正在追赶 - 如果启动延迟比即时搜索就绪更重要，则保持默认 `--no-wait-for-analysis` - 如果即时就绪比启动时间更重要，则使用 `--wait-for-analysis` ## 开发该项目使用 `Makefile` 来简化开发和测试。使用 `ruff` 进行代码检查和格式化，并使用 `pre-commit` 钩子确保代码质量。 ### 设置 1. **安装 `uv`**：如果你没有安装 `uv`，可以使用 pip 安装： ```bash pip install uv ``` 或者，按照官方 `uv` 安装指南：[https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/) 2. **创建虚拟环境并安装依赖**： ```bash make dev-setup source ./.venv/bin/activate ``` 3. **设置 Ghidra 环境变量**：下载并安装 Ghidra，然后将 `GHIDRA_INSTALL_DIR` 环境变量设置为你的 Ghidra 安装目录。 ```bash # For Linux / Mac export GHIDRA_INSTALL_DIR="/path/to/ghidra/" # For Windows PowerShell [System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27) ``` ### 测试与质量 `Makefile` 提供了多个测试和代码质量目标： - `make run`: 运行 MCP 服务器。 - `make test`: 运行完整的测试套件（单元测试和集成测试）。 - `make test-unit`: 运行单元测试。 - `make test-integration`: 运行集成测试。 - `make test-integration-fast`: 运行用于 pre-commit 的轻量级集成冒烟测试。 - `make test-integration-gui`: 运行 GUI 集成测试。需要可用的 Ghidra 安装和 GUI 支持。 - `make lint`: 使用 `ruff` 检查代码风格。 - `make format`: 使用 `ruff` 格式化代码。 - `make typecheck`: 使用 `ruff` 运行轻量级静态检查。 - `make check`: 运行所有质量检查。 - `make dev`: 运行开发工作流（格式化和检查）。 - `make build`: 构建分发包。 - `make clean`: 清理构建产物和缓存。推荐的分工： - pre-commit: `ruff`, `pyright`, 单元测试，以及一个轻量级集成冒烟测试 - GitHub Actions: 完整的 Linux 无头集成测试覆盖、在 `Xvfb` 下的 Linux GUI 测试、CLI 覆盖，以及当前的 macOS 冒烟测试 - 定时 CI: 较旧的 macOS / Ghidra 兼容性覆盖 - 本地/手动: 更重的特定环境 GUI 调试和发布完整性检查 ## API 接口 ### 工具允许 LLMs 执行操作、进行确定性计算并与外部服务交互。 #### 批量操作 `decompile_function` 和 `list_xrefs` 接受单个目标或目标列表，在分析调用链或同时分析多个符号时减少往返次数。```jsonc // Decompile three functions in one call, with callees and xrefs attached { "binary_name": "firmware.bin", "name_or_address": ["main", "init_hardware", "0x08001234"], "include_callees": true, "include_xrefs": true } // Get cross-references for multiple symbols at once { "binary_name": "firmware.bin", "name_or_address": ["malloc", "free", "realloc"] }

#### 读取/分析工具 - `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)`：使用语义向量搜索或字面匹配搜索反编译的伪C代码。 - `list_xrefs(binary_name: str, name_or_address: str | list[str])`：列出函数、符号或地址的交叉引用。接受单个目标或列表进行批量查找。 - `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)`：为指定函数生成MermaidJS调用图。支持“调用”（目标调用的函数）和“被调用”（调用目标的函数）两种方向，并提供多种可视化类型。 - `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)`：按名称或地址反编译函数。接受单个目标或列表进行批量反编译。丰富的响应标志可为每个结果附加被调用者、字符串和/或交叉引用。`timeout_sec` 应用于每个目标，并独立限制每次反编译尝试。 - `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`：列出指定二进制文件中的所有导出函数和符号（查询支持正则表达式）。 - `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`：列出指定二进制文件的所有导入函数和符号（查询支持正则表达式）。 - `read_bytes(binary_name: str, address: str, size: int = 32)`：从指定地址的内存中读取原始字节。十六进制地址可以包含或省略 `0x` 前缀。 - `search_strings(binary_name: str, query: str, limit: int = 100)`：在二进制文件中搜索字符串。 - `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`：按名称在二进制文件中搜索符号。支持正则表达式模式（例如 `^main$`、`func.*one`）进行不区分大小写的匹配，或纯子字符串查询。设置 `functions_only=True` 可排除标签、变量和其他非函数符号。 #### 项目操作 - `import_binary(binary_path: str)`：从指定路径将二进制文件导入当前Ghidra项目。如果路径是目录，它将递归扫描并导入所有支持的二进制文件，并在Ghidra项目中保留目录结构。 - `list_project_binaries()`：列出当前Ghidra项目中的二进制文件。在GUI模式下，这包括磁盘上存在但当前未在CodeBrowser中打开的项目二进制文件。 - `list_project_binary_metadata(binary_name: str)`：检索指定二进制文件的详细元数据，包括架构、编译器、可执行格式、分析指标和文件哈希。 - `delete_project_binary(binary_name: str)`：从Ghidra项目中删除二进制文件（程序）。 #### 编辑/变异工具 - `rename_function(binary_name: str, name_or_address: str, new_name: str)`：按名称或地址重命名函数。在GUI模式下，此操作作为实时Ghidra事务运行并更新打开的程序。 - `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`：在特定函数内按确切名称重命名函数参数或局部变量。如果该名称在函数内缺失或不明确，工具将返回错误而不是猜测。在GUI模式下，此操作作为实时Ghidra事务运行并更新打开的程序。 - `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`：在特定函数内按确切名称设置函数参数或局部变量的数据类型。如果该名称在函数内缺失或不明确，工具将返回错误而不是猜测。`type_name` 使用Ghidra的数据类型解析器针对程序数据类型管理器进行解析。 - `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`：从完整签名字符串设置函数原型。该工具始终通过Ghidra的原生签名解析器运行原型，如果原型无效则返回底层解析器或应用错误。 - `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`：设置函数/反编译器注释或列表注释。列表注释目标可以是地址、符号或函数。支持的 `comment_type` 值为 `decompiler`、`plate`、`pre`、`eol`、`post` 和 `repeatable`。 #### GUI控制工具（仅限`--gui`）这些工具仅在 `pyghidra-mcp` 以 `--gui` 启动时可用，用于控制GUI显示内容，而不是直接修改项目数据： - `list_open_programs()`：列出当前在Ghidra GUI中打开的程序。 - `open_program_in_gui(binary_name: str, new_window: bool = True)`：在CodeBrowser中打开项目二进制文件。默认情况下会打开一个新的CodeBrowser窗口。设置 `new_window=false` 以尽可能重用可见的CodeBrowser。 - `set_current_program(binary_name: str)`：使打开的程序成为主GUI工具上下文中的活动/当前程序。 - `goto(binary_name: str, target: str, target_type: str)`：将Ghidra GUI导航到地址或函数。`target_type` 必须是 `address` 或 `function`。 ## 用法此Python包已发布到PyPI，名称为 [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp)，可以使用 [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/) 或任何Python包管理器安装和运行。```text $ uvx pyghidra-mcp --help Usage: pyghidra-mcp [OPTIONS] [INPUT_PATHS]... PyGhidra Command-Line MCP server Options: -v, --version Show version and exit. -t, --transport [stdio|streamable-http|sse|http] Transport protocol. SSE is deprecated; use streamable-http instead. [default: stdio] -p, --port INTEGER Port for HTTP-based transports. [default: 8000] -o, --host TEXT Host for HTTP-based transports. [default: 127.0.0.1] --project-path PATH Directory for a pyghidra-mcp project or an existing Ghidra .gpr file. [default: pyghidra_mcp_projects] --project-name TEXT Ghidra project name. Ignored for .gpr paths. [default: my_project] --threaded / --no-threaded Allow threaded analysis. [default: threaded] --max-workers INTEGER Number of analysis workers; 0 means CPU count. [default: 0] --wait-for-analysis / --no-wait-for-analysis Wait for initial analysis before starting. [default: no-wait-for-analysis] --gui / --no-gui Launch Ghidra GUI in-process and serve MCP against GUI-open programs. Cannot attach to an already-running external Ghidra process. [default: no-gui] --list-project-binaries List ingested project binaries and exit. --delete-project-binary TEXT Delete a project binary by name and exit. --force-analysis / --no-force-analysis Force a new binary analysis each run. [default: no-force-analysis] --verbose-analysis / --no-verbose-analysis Verbose logging for analysis. [default: no-verbose-analysis] --no-symbols / --with-symbols Turn off symbols for analysis. [default: with-symbols] --sym-file-path PATH Single PDB symbol file for one binary. -s, --symbols-path PATH Local symbols directory. --gdt PATH Path to GDT files. May be specified multiple times. --program-options PATH JSON file with Ghidra program options. --gzfs-path PATH Location to store GZFs of analyzed binaries. -h, --help Show this message and exit.

pyghidra-mcp

最受欢迎

为代理进行优化

CLI 客户端

安装

快速开始使用 CLI

创建、管理和打开现有项目

创建新项目

自包含项目结构

基本项目创建```bash

Create a new project with default settings

Creates:

创建多个相关项目```bash

Create separate projects for different analysis focuses

Project for suspicious binaries

Project for packed malware

GUI 模式

使用Docker映射二进制文件

Create and populate the new directory

Run the Docker container with volume mapping

使用 Docker

Docker

服务器发送事件（SSE）

Python```bash

Integrations

Claude Desktop