Python 命令行 Ghidra MCP
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/41597/82f9c5eb55db6134d47587275fce66c4ed32b86b5332f7e2d610fa0214070a7f.png" 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/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
<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 模型上下文协议服务器
### 概述
**`pyghidra-mcp`** 是一个命令行模型上下文协议（MCP）服务器，它将 [Ghidra](https://ghidra-sre.org/)（一套强大的软件逆向工程（SRE）套件）的完整分析能力带入智能代理和基于 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 共享实时程序状态
> [!NOTE]
> 这个 beta 项目正在积极开发中。我们非常期待你的反馈、错误报告、功能请求和代码。
## 又一个 Ghidra MCP？
是的，最初的 [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) 非常出色。但 `pyghidra-mcp` 采用了不同的方法：
- 🐍 **无头优先，支持 GUI** – 完全通过 CLI 运行以实现简化的自动化，或者在需要实时 GUI 导航和编辑时使用 `--gui` 启动 Ghidra。
- 🔁 **为自动化而设计** – 非常适合与 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["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
```
### 选择模式
```mermaid
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"]
```
- **无头 MCP**：使用 `streamable-http`。它将 Ghidra 及其项目作为单个长期运行的服务器保持存活，并可与 MCP 主机和 CLI 客户端配合使用。
- **GUI 模式**：`pyghidra-mcp` 启动 Ghidra，打开项目，并暴露额外工具，在同一 JVM 中操控 CodeBrowser。
- **CLI 客户端**：`pyghidra-mcp-cli` 是一个 HTTP 客户端。先启动一个 `streamable-http` 服务器，然后针对该运行中的服务器发出终端命令。
- **stdio**：仅对无法连接到 HTTP 端点的 MCP 主机保留此方式。
<details>
<summary>详细架构与工具面</summary>
```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"]
McpServer["MCPServer 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 --> McpServer
Http --> McpServer
Sse --> McpServer
McpServer --> Context
Context --> PyGhidra
PyGhidra --> Jpype
Jpype --> Project
Project --> Programs
Context --> Indexing
Indexing --> Search
McpServer --> 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)
- [可流式 HTTP](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [标准输入/输出（stdio）](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [与 OpenWeb-UI 和 MCPO 配合使用](#using-with-openweb-ui-and-mcpo)
- [使用 `uvx`](#with-uvx)
- [使用 Docker](#docker-2)
- [服务器发送事件（SSE）](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [灵感来源](#inspiration)
- [贡献、社区及从源码运行](#contributing-community-and-running-from-source)
- [贡献者工作流](#contributor-workflow)
## 快速开始
使用 [Python 包](https://pypi.org/p/pyghidra-mcp) 和 [`uv`](https://docs.astral.sh/uv/guides/tools/) 启动一个持久化的可流式 HTTP 服务器：
```bash
uvx pyghidra-mcp \
--transport streamable-http \
--project-path /absolute/path/to/ghidra-projects \
/absolute/path/to/binary
```
然后服务器可在 `http://127.0.0.1:8000/mcp` 访问。保持其运行，并配置你的 MCP 客户端使用该 URL；下面的 [Claude Code](#claude-code) 和 [Codex](#codex) 示例展示了预期的配置。
要从 MCP 启动并控制实时 Ghidra GUI，请将 `--gui` 与 `streamable-http` 一起使用：
```bash
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
```
> [!IMPORTANT]
> `--gui` 通过 `pyghidra-mcp` 启动 Ghidra。它不会附加到已在运行的外部 Ghidra 实例。
或者，作为 [Docker 容器](https://ghcr.io/clearbluejar/pyghidra-mcp) 运行：
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## 针对 Agent 优化
`pyghidra-mcp` 有意保持 MCP 接口面狭窄，以便 agent 客户端在工具发现和参数选择上花费更少的 token。
- **简短的工具描述**：MCP 工具文档字符串保持紧凑，使 MCPServer 工具 schema 保持小巧，发送给模型的成本更低。
- **上下文纪律**：工具默认返回聚焦的结构化数据，而不是转储整个程序的上下文。反编译、符号搜索和交叉引用结果经过精心设计，以支持迭代分析，而非一次性返回大量响应。
- **仅在相关时提供 GUI 工具**：仅在服务器以 `--gui` 启动时，才会暴露 `open_program_in_gui`、`list_open_programs`、`set_current_program` 和 `goto` 等仅限 GUI 的控件。
- **CLI 是可选的**：如果 MCP 不是您偏好的接口，`pyghidra-mcp-cli` 提供了一个基于 HTTP 的直接命令行客户端，带有针对常见编辑和分析工作流的分组命令。
这使得默认服务器可用于 LLM agent、IDE 集成和自动化，而不会在无头会话中暴露不必要的工具接口面或仅限 GUI 的控件。
## CLI 客户端
如需更交互式的命令行体验，您可以使用单独的 **pyghidra-mcp-cli** 包，它提供了一个用户友好的界面，用于与运行中的 pyghidra-mcp 服务器进行交互。
### 安装
使用 [`uv`](https://docs.astral.sh/uv/)（推荐）安装 CLI 客户端：
```bash
uvx pyghidra-mcp-cli
```
或使用 pip 安装：
```bash
pip install pyghidra-mcp-cli
```
### CLI 快速开始
1. **启动服务器**（在一个终端中）：
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **使用 CLI**（在另一个终端中）：
```bash
# 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
```
> [!NOTE]
> CLI 通过 HTTP 连接到 pyghidra-mcp，以避免为每条命令启动新的 Ghidra 进程所带来的 10-60 秒启动开销。完整文档请参阅 [CLI README](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md)。
## 项目创建、管理及打开现有项目
### 创建新项目
你可以通过多种方式创建新项目，具体取决于你的工作流程：
#### 自包含项目结构
`pyghidra-mcp` 创建**自包含项目结构**，每个项目都有自己的 Ghidra 项目和 pyghidra-mcp 工件。这确保了完全隔离和便捷的项目管理。
#### 基本项目创建
```bash
# 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
```
#### 自定义项目创建
```bash
# 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
```
#### 创建多个相关项目
```bash
# 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 文件打开
```bash
# 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 的工具
示例：
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
当你想执行以下操作时，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/main/: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
### 工具
使 LLM 能够执行操作、进行确定性计算，并与外部服务交互。
#### 批量操作
`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"]
}
```
单项错误以内联方式返回（其他目标仍然成功）：
```jsonc
[
{"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)`：按名称或地址反编译函数。接受单个目标或列表以进行批量反编译。丰富的响应标志可将被调用者、字符串和/或交叉引用附加到每个结果。`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 包以 [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) 发布到 PyPI，可以使用 [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.
```
### 使用 Docker 映射二进制文件
使用 Docker 容器时，你可以将包含二进制文件的本地目录映射到容器的工作区中。这样 `pyghidra-mcp` 就能分析你的文件。
```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/*
```
### Streamable HTTP
Streamable HTTP 是推荐的传输方式。它使一个 Ghidra 进程和项目对 MCP 主机和 `pyghidra-mcp-cli` 保持可用，避免了每个客户端单独启动一个进程的开销。它通过 HTTP 发送 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
```bash
pyghidra-mcp -t streamable-http
```
Python 包默认使用 `stdio`，因此在启动服务器时始终需要包含 `--transport streamable-http`。
GUI 模式使用此传输方式：
```bash
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
```
### Claude Code
启动 HTTP 服务器后，将其添加到 Claude Code：
```bash
claude mcp add --transport http pyghidra-mcp http://127.0.0.1:8000/mcp
```
对于项目共享配置，请将以下内容添加到项目根目录的 `.mcp.json` 中：
```json
{
"mcpServers": {
"pyghidra-mcp": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}
```
`type: "http"` 是必需的：仅包含 `url` 的条目会被 Claude Code 视为 stdio 服务器。使用 `claude mcp list` 或 `/mcp` 来验证连接。
### Codex
启动 HTTP 服务器后，将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.pyghidra-mcp]
url = "http://127.0.0.1:8000/mcp"
```
保存配置后重启 Codex。服务器名称是任意的；`pyghidra-mcp` 是将出现在 Codex 中的名称。
### 标准输入/输出 (stdio)
仅当 MCP 主机无法使用 HTTP 端点时才使用 stdio。它会启动一个通过其父进程的标准输入和输出流进行通信的服务器。
#### Python
```bash
pyghidra-mcp --transport stdio
```
由于服务器通过标准输入和输出进行通信，它看起来会一直等待而没有终端输出；这是预期行为。
#### Docker
```bash
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 模式。
### 与 OpenWeb-UI 和 MCPO 配合使用
仅当 OpenWeb-UI 或其他使用方明确需要 OpenAPI 代理时，才使用 [MCPO](https://github.com/open-webui/mcpo)。对于普通的 MCP 客户端，请直接连接到上方的 Streamable HTTP 端点。
https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95
#### 使用 `uvx`
```bash
uvx mcpo -- pyghidra-mcp /bin/ls
```
#### 使用 Docker
```bash
uvx mcpo -- docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp /bin/ls
```
### 服务器发送事件（SSE）
> [!WARNING]
> MCP 社区认为这是一种遗留传输协议，旨在实现向后兼容。[Streamable HTTP](#streamable-http) 是推荐的替代方案。
SSE 传输通过 Server-Send Events 实现服务器到客户端的流式传输，用于客户端到服务器以及服务器到客户端的通信。有关更多详细信息，请参阅[规范](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
```bash
pyghidra-mcp -t sse
```
默认情况下，Python 包将以 `stdio` 模式运行，因此你需要包含 `-t sse`。
#### Docker
```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse
```
## 灵感来源
本项目的实现和设计灵感来源于以下优秀项目：
* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
* [semgrep-mcp](https://github.com/semgrep/mcp)
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)