# PyGhidra-MCP - Ghidra 模型上下文协议服务器
### 概述
**`pyghidra-mcp`** 是一个命令行模型上下文协议（MCP）服务器，它将强大的软件逆向工程（SRE）套件 [Ghidra](https://ghidra-sre.org/) 的完整分析能力引入了智能代理和基于 LLM 的工具的世界。
它使用 `pyghidra` 和 `jpype` 将 Ghidra 的 [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) 和 [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) 桥接到 Python，然后通过模型上下文协议公开该功能。
MCP 是一个统一的接口，允许语言模型、开发工具（如 VS Code）和自主代理访问结构化上下文、调用工具并进行智能协作。可以将 MCP 视为强大的分析工具与 LLM 生态系统之间的桥梁。
通过 `pyghidra-mcp`，Ghidra 成为了一个智能后端——准备好响应富含上下文的查询，自动执行深度的逆向工程任务，并集成到 AI 辅助的工作流中。
`pyghidra-mcp` 现在支持两种操作模式：
- `headless` 模式，用于 CLI 驱动的分析和自动化
- `--gui` 模式，该模式通过 `pyghidra-mcp` 启动 Ghidra，并与运行中的 GUI 共享实时程序状态
## 又一个 Ghidra MCP？
是的，原版的 [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) 非常出色。但 `pyghidra-mcp` 采用了一种不同的方法：
- 🐍 **无头优先，支持 GUI** – 完全通过 CLI 运行以实现简化的自动化，或者在需要实时 GUI 导航和编辑时使用 `--gui` 启动 Ghidra。
- 🔁 **为自动化而生** – 非常适合与 LLM、CI 流水线以及需要可重复行为的工具集成。
- ✅ **对 CI/CD 友好** – 为客户端和服务器会话构建了健壮的单元和集成测试。
- 🚀 **快速启动** – 异步启动允许服务器在二进制文件仍在后台分析时就开始处理请求。支持以最少的设置快速启动命令行。
- 📦 **项目级分析** – 支持对 Ghidra 项目中的所有二进制文件进行并发逆向工程
- 🤖 **Agent 就绪** – 为智能代理驱动的工作流和大规模逆向工程自动化而构建。
- 🔍 语义代码搜索 – 使用向量嵌入（通过 ChromaDB）支持跨反编译函数、注释和符号的快速、模糊查找——非常适合伪 C 探索和代理驱动的分类。
本项目提供了为本地开发、无头环境和可测试工作流优化的 Python 优先体验。
## 设置图解
### 各组件如何连接
```
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
.gpr / .rep"]
Artifacts["MCP artifacts
ChromaDB + GZF cache"]
Gui["Ghidra GUI / CodeBrowser
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
```
### 选择模式
```
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
or -t streamable-http"]
GuiNeed --> GuiMode["pyghidra-mcp --gui
--transport streamable-http
--project-path project.gpr"]
Terminal --> HttpServer["Start pyghidra-mcp
--transport streamable-http"]
HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]
```
- **Headless MCP**：本地 MCP 主机使用 `stdio`，或者当多个客户端需要同一个长期运行的 Ghidra 项目时使用 `streamable-http`。
- **GUI 模式**：`pyghidra-mcp` 启动 Ghidra，打开项目，并公开额外的工具以在同一个 JVM 中控制 CodeBrowser。
- **CLI 客户端**：`pyghidra-mcp-cli` 是一个 HTTP 客户端。首先启动一个 `streamable-http` 服务器，然后针对该正在运行的服务器发出终端命令。
详细架构与工具接口
```
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
```
## 目录
- [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)
- [为 Agent 优化](#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)
- [Streamable 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 命令运行：
```
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default
```
要通过 MCP 启动并控制实时的 Ghidra GUI，请将 `--gui` 与 `streamable-http` 结合使用：
```
uvx pyghidra-mcp \
--gui \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--project-path /absolute/path/to/ghidra-projects \
--project-name my_project
```
或者，作为 [Docker 容器](https://ghcr.io/clearbluejar/pyghidra-mcp)运行：
```
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio
```
## 为 Agent 优化
`pyghidra-mcp` 有意保持 MCP 接口精简，以便 Agent 客户端在工具发现和参数选择上消耗更少的 token。
- **简短的工具描述**：MCP 工具的文档字符串保持紧凑，以便 FastMCP 工具模式保持轻量且发送给模型的成本更低。
- **上下文纪律**：工具默认返回聚焦的结构化数据，而不是转储整个程序的上下文。反编译、符号搜索和交叉引用结果的形状旨在支持迭代分析，而不是一次性给出巨大的响应。
- **仅在相关时提供 GUI 工具**：仅当服务器使用 `--gui` 启动时，才会公开仅限 GUI 的控制项（如 `open_program_in_gui`、`list_open_programs`、`set_current_program` 和 `goto`）。
- **CLI 是可选的**：如果 MCP 不是您首选的接口，`pyghidra-mcp-cli` 提供了一个基于 HTTP 的直接命令行客户端，其中包含用于常见编辑和分析工作流的分组命令。
这使得默认服务器可用于 LLM 代理、IDE 集成和自动化，而不会在无头会话中暴露不必要的工具接口或仅限 GUI 的控制项。
## CLI 客户端
为了获得更具交互性的命令行体验，您可以使用独立的 **pyghidra-mcp-cli** 包，它提供了一个用户友好的界面，用于与正在运行的 pyghidra-mcp 服务器进行交互。
### 安装说明
使用 [`uv`](https://docs.astral.sh/uv/) 安装 CLI 客户端（推荐）：
```
uvx pyghidra-mcp-cli
```
或者使用 pip 安装：
```
pip install pyghidra-mcp-cli
```
### CLI 快速入门
1. **启动服务器**（在一个终端中）：
```
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **使用 CLI**（在另一个终端中）：
```
# List available binaries
pyghidra-mcp-cli list binaries
# Decompile a function
pyghidra-mcp-cli decompile --binary ls main
# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs
# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10
```
## 项目创建、管理及打开现有项目
### 创建新项目
您可以根据工作流以多种方式创建新项目：
#### 独立项目结构
`pyghidra-mcp` 创建一个**独立的项目结构**，其中每个项目都有自己的 Ghidra 项目和 pyghidra-mcp 产物。这确保了完全的隔离和便捷的项目管理。
#### 基础项目创建
```
# Create a new project with default settings
pyghidra-mcp
# Creates:
$ tree pyghidra_mcp_projects/
pyghidra_mcp_projects/
├── my_project.gpr
├── my_project-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── my_project.rep
```
#### 自定义项目创建
```
# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis
$ tree ~/analysis/
/home/vscode/analysis/
└── malware_study
├── malware_analysis.gpr
├── malware_analysis-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── malware_analysis.rep
```
#### 创建多个相关项目
```
# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace
# Project for suspicious binaries
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
# Project for packed malware
pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis
```
### 打开现有 Ghidra 项目
如果您有现有的 Ghidra 项目（`.gpr` 文件），可以直接使用 `pyghidra-mcp` 打开它们：
#### 通过 .gpr 文件打开
```
# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr
# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)
```
### GUI 模式
当您希望 MCP 操作针对 Ghidra 正在显示的相同实时程序对象时，请使用 GUI 模式。
- `--gui` 需要 `--transport streamable-http`（或使用别名 `--transport http`）
- `--project-path` 可以是项目目录加上 `--project-name`，或者是现有的 `.gpr` 文件。缺失的项目将被自动创建。
- Ghidra 由 `pyghidra-mcp` 启动，这会将 GUI 和 MCP 事务保持在同一个 JVM 中
- 仅限 GUI 的工具仅在以 `--gui` 运行时公开
示例：
```
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
在以下情况下，GUI 模式是正确的选择：
- 在 CodeBrowser 中打开或切换程序
- 将 listing 导航到函数或地址
- 重命名函数或添加注释，并立即在 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 进行安装：
pip install uv
或者，遵循官方的 `uv` 安装指南：[https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **创建虚拟环境并安装依赖项**：
make dev-setup
source ./.venv/bin/activate
3. **设置 Ghidra 环境变量**：下载并安装 Ghidra，然后将 `GHIDRA_INSTALL_DIR` 环境变量设置为您的 Ghidra 安装目录。
# For Linux / Mac
export GHIDRA_INSTALL_DIR="/path/to/ghidra/
# For Windows PowerShell
[System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\path\to\ghidra')
### 测试与质量
`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 headless 集成覆盖，在 `Xvfb` 下的 Linux GUI，CLI 覆盖，以及当前的 macOS 冒烟测试
- 计划的 CI：较旧的 macOS / Ghidra 兼容性覆盖
- 本地/手动：较重的特定环境 GUI 调试和发布健全性检查
## API
### 工具
使 LLM 能够执行操作、进行确定性计算以及与外部服务交互。
#### 批量操作
`decompile_function` 和 `list_xrefs` 接受单个目标或目标列表，从而在分析调用链或多个符号时减少往返次数。
```
// 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"]
}
```
单项错误将内联返回（其他目标仍会成功）：
```
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### 读取 / 分析工具
- `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 调用图。支持“calling”（目标调用的函数）和“called”（调用目标的函数）方向以及多种可视化类型。
- `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)`：按名称或地址反编译函数。接受单个目标或列表用于批量反编译。丰富的响应标志会将 callees、strings 和/或 xrefs 附加到每个结果中。`timeout_sec` 适用于每个目标，并独立限制每次反编译尝试。
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`：列出指定二进制文件中所有导出的函数和符号（query 支持 regex）。
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`：列出指定二进制文件的所有导入函数和符号（query 支持 regex）。
- `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)`：按名称在二进制文件中搜索符号。支持 regex 模式（例如 `^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)`：设置函数/反编译器注释或 listing 注释。Listing 注释目标可以是地址、符号或函数。支持的 `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 包管理器进行安装和运行。
```
$ 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.
```
### 使用 Docker 映射二进制文件
使用 Docker 容器时，您可以将包含二进制文件的本地目录映射到容器的工作区中。这允许 `pyghidra-mcp` 分析您的文件。
```
# 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/*
```
### 与 OpenWeb-UI 和 MCPO 结合使用
您可以使用 [MCPO](https://github.com/open-webui/mcpo)（一个 MCP 到 OpenAPI 的代理）将 `pyghidra-mcp` 与 [OpenWeb-UI](https://github.com/open-webui/open-webui) 集成。这允许您通过标准的 RESTful API 公开 `pyghidra-mcp` 的工具，使它们能够被 Web 界面和其他工具访问。
https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95
#### 使用 `uvx`
您可以使用 `uvx` 同时运行 `pyghidra-mcp` 和 `mcpo`：
```
uvx mcpo -- \
pyghidra-mcp /bin/ls
```
#### 使用 Docker
您可以将 mcpo 与 Docker 结合使用：
```
uvx mcpo -- docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp /bin/ls
```
### 标准输入/输出 (stdio)
stdio 传输支持通过标准输入和输出流进行通信。这对于本地集成和命令行工具特别有用。有关详细信息，请参阅 [规范](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types)。
#### Python
```
pyghidra-mcp
```
默认情况下，Python 包将在 `stdio` 模式下运行。由于它使用标准输入和输出流，看起来会像是工具挂起而没有任何输出，但这是预期行为。
#### Docker
此服务器已发布到 GitHub 的 Container Registry ([ghcr.io/clearbluejar/pyghidra-mcp](http://ghcr.io/clearbluejar/pyghidra-mcp))
```
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio
```
默认情况下，Docker 容器启动 `streamable-http` 服务器，因此需在镜像名称后包含 `-t stdio`，并以 `-i` 运行以进入[交互式](https://docs.docker.com/reference/cli/docker/container/run/#interactive) stdio 模式。
### Streamable HTTP
Streamable HTTP 支持通过 HTTP POST 请求基于 JSON RPC 进行流式响应。有关详细信息，请参阅 [规范](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http)。
默认情况下，服务器在 [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) 上监听客户端连接。使用 `--host` / `--port` 或 `MCP_HOST` / `MCP_PORT` 环境变量更改绑定地址。*客户端连接时服务器必须处于运行状态。*
#### Python
```
pyghidra-mcp -t streamable-http
```
默认情况下，Python 包将在 `stdio` 模式下运行，因此您必须包含 `-t streamable-http`。
GUI 模式使用此传输方式：
```
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_project.gpr
```
#### Docker
```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
### 服务器发送事件 (SSE)
SSE 传输支持使用服务器发送事件进行服务器到客户端和客户端到服务器的通信。有关详细信息，请参阅 [规范](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse)。
默认情况下，服务器在 [http://127.0.0.1:8000/sse](http://127.0.0.1:8000/sse) 上监听客户端连接。使用 `--host` / `--port` 或 `MCP_HOST` / `MCP_PORT` 环境变量更改绑定地址。*客户端连接时服务器必须处于运行状态。*
#### Python
```
pyghidra-mcp -t sse
```
默认情况下，Python 包将在 `stdio` 模式下运行，因此您必须包含 `-t sse`。
#### Docker
```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse
```
## 集成
### Claude Desktop
将以下 JSON 块添加到您的 `claude_desktop_config.json` 文件中：
```
{
"mcpServers": {
"pyghidra-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/clearbluejar/pyghidra-mcp",
"pyghidra-mcp",
"--project-path",
"/tmp/pyghidra", // or path to writeable directory
"/bin/ls" //
],
"env": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra/ghidra_12.0_PUBLIC"
}
}
}
}
```
## 灵感来源
本项目的实现和设计受到了以下优秀项目的启发：
* [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)
## 贡献、社区及从源码运行
我们相信逆向工程的未来是代理化、上下文化和可扩展的。
`pyghidra-mcp` 是迈向该未来的一步——使完整的 Ghidra 项目可供 AI 代理和自动化流水线访问。
我们正在积极开发本项目，并欢迎反馈、Issue 和贡献。
### 贡献者工作流
如果您要添加新工具或集成，以下是推荐的工作流：
- 为您的分支加上 `feature/` 前缀标签，以表明这是一项新功能。
- 使用与 `pyghidra/tools/` 中现有工具相同的风格和结构添加您的工具。
- 编写一个集成测试，使用 `StdioClient` 实例测试您的工具。将其放置在 `tests/integration/` 中。
- 通过在 `tests/integration/test_concurrent_streamable_client.py` 中添加对您工具的调用来扩展并发测试。
- 运行 make test 和 make format，以确保您的更改通过所有测试并符合代码检查规则。
这确保了整个代码库的一致性，并帮助我们为逆向工程工作流维护健壮、可扩展的工具。
Made with ❤️ by the [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)