Ghidra MCP 服务器

如果你觉得这个项目有用，请 ⭐ 给仓库加星——这能帮助更多人发现它！

如果 Ghidra MCP 节省了你的时间，请考虑赞助该项目。单次捐赠和定期捐赠都有助于支持兼容性更新、生产级加固、文档和新的工具开发。

一个生产就绪的模型上下文协议（MCP）服务器，将 Ghidra 强大的逆向工程能力与现代 AI 工具和自动化框架连接起来。271 个 MCP 工具、经过实战验证的 AI 工作流，以及当前最全面的 Ghidra-MCP 集成——现已包含 P-code 模拟、实时调试器集成和 PCode-graph 数据流分析。

为什么选择 Ghidra MCP？

大多数 Ghidra MCP 实现只提供少量只读工具就完事了。这个项目不同——它由一位每天在实际二进制文件上使用的逆向工程师构建，而非仅作演示。

• 271 个 MCP 工具——比任何竞品实现多 3 倍。不仅仅是读取操作——完全写入权限，支持重命名、类型标注、注释、结构创建、脚本执行、P-code 模拟和实时调试。
• 经过实战验证的 AI 工作流——成熟的文件工作流（V5）经过数百个函数的打磨。包含分步提示、匈牙利命名法参考、批量处理指南和孤立代码发现。
• 生产级可靠性——原子事务、批量操作（减少 93% 的 API 调用）、可配置超时和优雅的错误处理。无静默失败。
• 跨二进制文件文档传输——SHA-256 函数哈希匹配可在不同二进制版本间自动传播文档。一次记录，处处应用。
• 完整的 Ghidra 服务器集成——连接共享 Ghidra 服务器、管理仓库、版本控制、签出/签入工作流以及多用户协作。
• 无头模式和 GUI 模式——可在有或无 Ghidra GUI 的情况下运行。支持 Docker，适用于 CI/CD 管道和大规模自动化分析。
• 有意为之的设计——v5.0 将命名约定、类型安全和文档标准移至工具层。AI 代理和人类工程师无需在每个提示中贴入风格指南即可产生一致的输出。

约定强制执行

你一定见过这种场景：项目进行到六个月时，你在同一个代码库中发现了 ProcessItem、process_items、handleItem 和 ItemProc——四个做同样事情的函数，由四个不同的会话或工程师命名，没有任何共享约定。修复它花费的时间远超所需，而问题还会再次发生。

v5.0 将约定从“需要记住的事情”移入工具层，在那里它们才能真正得到强制执行。

对于 AI 代理，这意味着每次会话、每个模型、每次运行都能产生一致的输出——无需在每个提示中粘贴风格指南。工具知道规则，模型只需做出调用。

对于团队，它消除了整个类别的评审评论，即“这不是我们的命名约定”。约定仲裁留在了工具中，而不是代码评审中。

对于大规模个人工作，analyze_function_completeness 给出了一个 0–100% 的评分，诚实衡量：结构性推断（无法修复的编译器产物）在你的有效评分中被原谅，对数缩放防止一个坏类别埋没一切，分层的井号注释质量让你确切知道缺少什么以及为什么。

🌟 特性

核心 MCP 集成

• 完整的 MCP 兼容性——模型上下文协议的完整实现
• 271 个 MCP 工具——覆盖二进制分析每个方面的全面 API 接口
• 生产就绪的可靠性——原子事务、批量操作、可配置超时
• 实时分析——与 Ghidra 分析引擎的实时集成

兼容性说明： MCP 工具名称已针对 GitHub Copilot CLI 和 CAPI 验证进行规范化。公开的工具名称仅使用小写字母、数字、下划线和连字符；嵌套的 HTTP 路径（如 /debugger/status）在需要避免与静态桥接工具冲突时，会以 debugger_status_2 这样的名称发布。

二进制分析能力

• 函数分析——反编译、调用图、交叉引用、完整性评分
• 数据流分析——来自任何变量或寄存器的 PCode-graph 值传播（正向/反向）
• 数据结构发现——创建结构体/联合体/枚举，包含字段分析和命名建议
• 字符串提取——正则表达式搜索、质量过滤、基于字符串的函数发现
• 导入/导出分析——符号表、外部位置、序号导入解析
• 内存与数据检查——原始内存读取、字节模式搜索、数组边界检测
• 跨二进制文件文档——函数哈希匹配和跨版本文档传播

动态分析（v5.4.0）

• P-code 模拟——通过 Ghidra 的 EmulatorHelper 隔离运行任意函数；毫秒级暴力破解 API 哈希
• 实时调试器集成——通过 Ghidra 的 TraceRmi 框架提供 17 个 Java 端点 + 22 个 Python 桥接工具（Windows PE 上使用 dbgeng，否则使用 gdb/lldb）：附加、单步、断点、寄存器、内存读取、非阻塞函数跟踪、ASLR 感知的静态↔动态地址转换

AI 驱动的逆向工程工作流

• 函数文档工作流 V5——完整函数文档的 7 步流程，包含匈牙利命名法、类型审核和自动验证评分
• 批量文档——并行子代理调度，同时记录多个函数
• 孤立代码发现——自动扫描器在已知代码间的空白区域发现未探索函数
• 数据类型调查——系统化的结构发现和字段分析工作流
• 跨版本匹配——基于哈希的函数匹配，跨越不同二进制版本

开发与自动化

• Ghidra 脚本管理——完全通过 MCP 创建、运行、更新和删除 Ghidra 脚本
• 多程序支持——在多个打开的程序之间切换和比较
• 批量操作——批量重命名、注释、类型标注和标签管理（API 调用减少 93%）
• 无头服务器——无需 Ghidra GUI 的完整分析——支持 Docker 和 CI/CD
• 项目与版本控制——创建项目、管理文件、Ghidra 服务器集成
• 分析控制——以编程方式列出、配置和触发 Ghidra 分析器

🚀 快速开始

前提条件

• Java 21 LTS（推荐 OpenJDK）
• Apache Maven 3.9+
• Ghidra 12.1.2（或兼容版本）
• Python 3.10+，包含 uv（推荐）或 pip + venv

共享 Ghidra 服务器用户：Ghidra 12.1.2 客户端需要 Ghidra 服务器为 12.1、12.0.5 或更新的兼容版本。请在使用此插件之前升级服务器至 12.1 客户端。

Ghidra 12.1.2 将 Jython 作为可选扩展附带。Java 脚本默认工作，但 ghidra_scripts/ 中的 .py 脚本需要从 文件 > 安装扩展 安装 Jython 扩展并重启 Ghidra。

安装

所有平台推荐：直接使用 python -m tools.setup。

ensure-prereqs 安装运行时 Python 需求以及所需 Ghidra JAR 到本地 Maven 仓库。 deploy 复制构建输出、安装用户配置文件扩展并修补 Ghidra 用户配置。

1. 克隆仓库： ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. 推荐：先运行环境预检： ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. 构建并部署到Ghidra： ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy 在需要时保存/关闭已在运行的匹配 Ghidra 实例，安装扩展，启动 Ghidra，等待 MCP 健康状态，并运行模式冒烟测试。

4. 可选严格/手动模式 (高级): ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. 显示命令帮助： ```text python -m tools.setup --help
   root@kitploit:~

6. 可选仅构建模式（高级/故障排除）： ```text python -m tools.setup build
   root@kitploit:~

Supported build path: python -m tools.setup build 在底层使用 Maven，是仓库任务和文档使用的规范工作流。 ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

I apologize, but I don't see any actual text content to translate in your message. The input appears to be empty after "INPUT:". Could you please provide the chunk of Markdown content you'd like translated?   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

安装 (Linux — Ubuntu/Debian)

1. 克隆仓库： ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. 安装系统先决条件（如果尚未安装）： ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

Debian/Kali/Ubuntu 23.04+ 说明 (PEP 668): 这些发行版将系统 Python 标记为外部管理，因此裸的 pip install 会失败，错误为 error: externally-managed-environment。不要使用 --break-system-packages 来绕过——这可能会损坏 apt 管理的工具。相反，请使用 uv（推荐——它自动创建并管理项目本地的 .venv，本仓库的命令正是使用它）：

root@kitploit:~

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # resolves deps into .venv and starts the bridge

或者使用传统的虚拟环境：

root@kitploit:~

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

3. 运行环境预检: ```bash python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

4. 构建并部署到 Ghidra（单条命令）： ```bash python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

这将：

• 将 Ghidra JAR 依赖安装到本地的 ~/.m2/repository
• 使用 Maven 构建 GhidraMCP-<version>.zip
• 将扩展解压到 ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/
• 使用 LastExtensionImportDirectory 更新 preferences
• 安装 Python 依赖

5. 可选：仅设置 Maven 依赖： ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. 显示命令帮助： ```bash python -m tools.setup --help
   root@kitploit:~

Linux 路径： 扩展安装至 $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/。 Ghidra 配置文件位于 $HOME/.config/ghidra/ghidra_<version>_PUBLIC/。

安装 (macOS — Homebrew)

1. 安装先决条件： ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. 克隆仓库： ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. 将 Ghidra JAR 安装到本地 Maven 中： ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. 构建和部署: ```bash python -m tools.setup ensure-prereqs
   --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

The extension is installed to ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.

注意： 使用 Homebrew 路径时需要 --ghidra-version，因为路径中不包含版本字符串。

5. 启动 Ghidra 并启用插件： ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

在主项目窗口中：Tools > GhidraMCP > Start MCP Server

6. 配置 Cursor/Claude MCP (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

安装（Arch Linux — AUR）

@Pandoriaantje 维护社区 AUR 包：

• ghidra-mcp-git — 跟踪 main 分支
• ghidra-mcp — 跟踪已发布版本

使用你偏好的 AUR 助手安装，例如：```bash yay -S ghidra-mcp # or ghidra-mcp-git

### 基本用法

#### 选项 1: Stdio 传输（推荐用于 AI 工具）```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

要将桥接从克隆的检出添加到 Autohand Code：```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

在`ghidra`之前添加`--scope project`，将服务器保存到当前项目的`.autohand`配置中，而不是您的用户配置。

#### 选项2：可流式HTTP传输（推荐用于Web/HTTP客户端）```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

MCP 客户端配置用于 HTTP 传输（添加到您的客户端的 MCP 配置文件中）：```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

基于浏览器的客户端（如 [MCP Inspector](https://github.com/modelcontextprotocol/inspector)）开箱即用：HTTP 传输方式会响应 CORS 预检（`OPTIONS`）请求，并将 `mcp-session-id` / `mcp-protocol-version` 头部暴露给脚本。允许的来源镜像了 Host 头部策略——始终允许任意端口上的回环地址，以及绑定主机和 `GHIDRA_MCP_ALLOWED_HOSTS` 中列出的任何主机。

#### 选项 3：SSE 传输（已弃用——请改用 streamable-http）```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

桥接高级标志

严格的程序路由（多程序安全）

设置 GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 使桥接拒绝任何省略程序选择器的程序范围调用，返回明确的错误，而不是让调用使用服务器的共享“当前程序”（即 switch_program 和活动 GUI 标签移动的那个）。```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

如果没有这个，省略 `program=` 的调用会针对当前程序运行，这在单程序工作流中没问题，但一旦打开多个程序就存在风险：该调用可能会读取或编辑错误的二进制文件而不报错。当多个客户端共享一个服务器时，风险更大，因为每个客户端都会将那个当前程序全局变量从其他客户端脚下移走。

启用严格模式后，每个程序作用域的调用都必须指定其目标。这涵盖了所有选择已打开程序的选定器：普通的 `program=` 以及跨程序工具的 `source_program`/`target_program` 或 `program_a`/`program_b`（声明为必需，但服务器在其中一个为空时仍会回退到当前程序）。被遗忘的选定器会在第一次错误调用时表现为响亮的错误，而不是静默写入错误的二进制文件。没有程序选定器的工具（`open_program` 和 `close_program` 接受 `path`/`name`）不受影响。默认关闭：变量未设置时，桥接器会原样发送调用。

#### 减少工具上下文开销

桥接器暴露了一个庞大的目录。为了保持模型的工具表面小巧，使用 `--lazy` 运行（连接时仅加载 `listing,function,program`），并让模型按需**发现**其余工具，而不是注册所有内容：

- `search_tools("rename function")` — 在**整个**目录中进行关键词搜索，包括其组未加载的工具。每个结果都会说明该工具现在是否可调用，如果不可调用，则提供确切的 `load_tool_group(...)` 调用来启用它。
- `list_tool_groups()` — 列出所有类别及其加载状态。
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — 在运行时加载或卸载一个类别。
- `check_tools("rename_or_label,batch_set_comments")` — 确认特定工具当前是否可调用。

`search_tools` 在急切模式和 `--lazy` 模式下均有效，因此遵循 `tools/list_changed` 的代理无需预先承担上下文成本即可获得完整的发现能力。

#### 可选：启动独立调试器服务器```bash
uv sync --group debugger
uv run python -m debugger

调试器服务器默认监听 http://127.0.0.1:8099/，MCP 桥暴露的 debugger_* 代理工具需要它。

调试器服务器标志：

如果更改了默认端口或主机，请在 .env 中设置 GHIDRA_DEBUGGER_URL，以便桥能够找到它。

在 Ghidra 中

1. 启动 Ghidra 并打开一个 CodeBrowser 窗口
2. 在 CodeBrowser 中，通过 File > Configure > Configure All Plugins > GhidraMCP 启用插件
3. 可选：通过 CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server 配置自定义端口
4. 通过 Tools > GhidraMCP > Start MCP Server 启动服务器
5. 服务器默认运行在 http://127.0.0.1:8089/

验证是否正常工作```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## 支持本项目

如果 Ghidra MCP 为您节省了工程或逆向工程时间，请考虑[赞助该项目](https://github.com/sponsors/bethington)。

- 一次性赞助有助于资助修复、兼容性更新和发布工作。
- 定期赞助有助于持续推进维护、文档和生产加固。
- 公司支持有助于优先考虑桥接、无头服务器、调试器集成和工作流工具的长期可靠性。

## 🔒 安全性

GhidraMCP 设计为**仅限 localhost 开发**。默认配置——HTTP 服务器绑定到 `127.0.0.1`，无身份验证——在受信任的单用户工作站上是安全的，并且与 v5.4.1 之前的行为一致。

**如果要将服务器暴露在回环之外，请先配置以下三个环境变量。** 如果没有令牌，服务器拒绝在非回环绑定上启动。

| 环境变量 | 效果 |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | 设置后，每个 HTTP 请求必须携带 `Authorization: Bearer <token>`。时间安全的比较。`/mcp/health`、`/health`、`/check_connection` 豁免。 |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | 设置为 `1`、`true` 或 `yes` 以启用 `/run_script_inline` 和 `/run_ghidra_script`。**从 v5.4.1 开始默认关闭**——这些端点对 Ghidra 进程执行任意 Java。在无头模式下，这还会在服务器启动时触发 OSGi `BundleHost` 初始化（Felix 框架，约数百毫秒）；如果不需要脚本执行，请保持关闭。 |
| `GHIDRA_MCP_FILE_ROOT` | 设置为目录路径后，文件系统路径端点（`/load_program`、`/import_file`、`/open_project`、`/delete_file` 等）对输入进行规范化，并要求其位于此根路径下。防止路径遍历。 |

名称质量强制与安全性是分开的。默认情况下，`rename_function_by_address` 和全局写入端点拒绝未通过内置质量门控的名称，结构体字段写入应用内置字段前缀约定。通过 **编辑 > 工具选项 > GhidraMCP HTTP 服务器 > 严格命名强制** 禁用内置约定层。同一个工具选项复选框涵盖 `rename_data`、`rename_global_variable`、`set_global`、`apply_data_type` 前缀/类型保护，以及 `create_struct`、`add_struct_field` 和 `modify_struct_field` 中的结构体字段匈牙利前缀自动修复。该设置会在 MCP 服务器启动或重启时读取。禁用强制后，函数/全局约定警告仍会返回。

### 示例：通过身份验证暴露到私有局域网```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

Ghidra Server 认证

当连接到共享的 Ghidra Server 时，GhidraMCP 可以自动抑制密码对话框。它按以下顺序解析凭据（第一个非空值生效）：

兼容性说明：Ghidra 12.1.2 客户端需要 Ghidra Server 12.1.2、12.0.5 或更新的兼容服务器。较旧的共享服务器不适合 12.1 客户端升级。

1. GHIDRA_SERVER_PASSWORD 环境变量（或 Ghidra 安装目录或 ~ 中的 .env 文件）
2. ~/.ghidra-cred — 你主目录中的单行密码文件
3. <ghidra-install-dir>/.ghidra-cred

用户名以类似方式解析：GHIDRA_SERVER_USER 环境变量 → user.name 系统属性。

如果未找到密码，Ghidra 会显示正常的 GUI 提示。在 .env 中设置这些（参见 .env.template 了解完整块）以启用静默认证。

从 v5.4.0 迁移到 v5.4.1

• 脚本端点现在默认关闭。 如果你依赖 /run_script_inline 或 /run_ghidra_script，请导出 GHIDRA_MCP_ALLOW_SCRIPTS=1。这是一个有意的破坏性变更；之前的默认设置不安全。
• 仅本地主机部署无需更改。 认证、绑定拒绝和路径根检查均为可选加入。

❓ 故障排除

工具中未出现 "GhidraMCP" 菜单

原因： 插件未启用或安装不正确。

解决方案：

1. 验证扩展是否已安装：文件 > 安装扩展 — GhidraMCP 应列出
2. 启用插件：文件 > 配置 > 配置所有插件 > GhidraMCP（勾选复选框）
3. 安装/启用后 重新启动 Ghidra

服务器无响应 / 连接被拒绝

原因： 服务器未启动或端口错误。

解决方案：

1. 确保你已启动服务器：工具 > GhidraMCP > 启动 MCP 服务器
2. 检查配置的端口：编辑 > 工具选项 > GhidraMCP HTTP 服务器
3. 检查端口是否被占用： ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. 在 Ghidra 控制台中查找错误：Window > Console

pip install 失败，报错 error: externally-managed-environment

原因： PEP 668。Debian 系列发行版（Debian 12+、Kali、Ubuntu 23.04+）将系统 Python 标记为外部管理，因此全局 pip install 被阻止，以保护由 apt 管理的软件包。

解决方案： 使用虚拟环境——切勿使用 --break-system-packages。推荐使用 uv，它可以自动管理项目本地的 .venv：```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

或者一个经典的 venv:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger 因 pybag 或 comtypes 出现 ModuleNotFoundError 而失败

原因： 独立调试器服务器使用了可选的仅 Windows 的 Python 依赖项，这些依赖项默认未安装。

解决方案：```text uv sync --group debugger uv run python -m debugger

如果你同时安装了全局 Python 和项目虚拟环境，请确保安装并运行在同一个解释器中。

### 500 内部服务器错误

**原因：** 服务器端异常，通常由程序数据缺失导致。

**解决方案：**
1. 确保在 CodeBrowser 中加载了二进制文件
2. 先运行自动分析：**Analysis > Auto Analyze**
3. 检查 Ghidra 控制台（**Window > Console**）中的 Java 异常
4. 某些操作需要完全分析的二进制文件

### 404 未找到错误

**原因：** 端点不存在或 URL 错误。

**解决方案：**
1. 验证端点是否存在：`curl http://127.0.0.1:8089/get_version`
2. 检查端点名称中是否有拼写错误
3. 确保使用了正确的 HTTP 方法（GET 与 POST）

### Python Ghidra 脚本失败，显示“未找到脚本提供程序”

**原因：** 在 Ghidra 12.1.2 中，Jython 支持默认不再启用。`.py` 脚本需要捆绑的 Jython 扩展；Python 3 脚本应使用 PyGhidra，而非 Ghidra 脚本管理器。

**解决方案：**
1. 在 Ghidra 前端中，打开 **File > Install Extensions**。
2. 勾选 **Jython**，重启 Ghidra，然后刷新脚本管理器。
3. 对于新的自动化任务，优先使用 Java Ghidra 脚本或 PyGhidra。

### 扩展未显示在“安装扩展”中

**原因：** JAR 文件位于错误的位置。

**解决方案：**
1. 手动安装位置：`~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. 或者使用：**File > Install Extensions > Add** 并选择 ZIP 文件
3. 确保 JAR/ZIP 是为你的 Ghidra 版本构建的

### 构建失败，显示“未找到 Ghidra 依赖项”

**原因：** Ghidra JAR 未安装在本地 Maven 仓库中。

**解决方案：**```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 生产性能

• MCP工具: 已完全实现271个工具
• 速度: 大多数操作响应时间低于1秒
• 效率: 通过批量操作减少93%的API调用
• 可靠性: 具有全有或全无语义的原子事务
• AI工作流: 经过数百个实际功能验证的文档提示
• 部署: 自动化的版本感知部署脚本

🛠️ API参考

271个MCP工具，由HTTP端点支持，按目录类别分组。由tests/endpoints.json通过python -m tools.gen_readme_api_reference --write生成；运行时的权威模式是/mcp/schema上的实时模式。使用模式：docs/prompts/TOOL_USAGE_GUIDE.md。

程序与会话管理

• analysis_status - 获取打开程序的最新分析状态
• close_program - 通过项目路径或名称关闭已打开的程序
• create_property_map - 创建一个用户属性映射，用于存储按地址索引的键入值
• delete_property_map - 删除一个用户属性映射及其所有值
• exit_ghidra - 保存并退出Ghidra
• get_address_spaces - 列出程序中的所有物理地址空间和覆盖地址空间（覆盖包括is_overlay标志和overlayed_space名称）
• get_current_program_info - 获取当前程序信息
• get_language_metadata - 导出程序的语言描述：地址空间、寄存器、默认符号、字节序、指针大小（issue #192）
• get_program_options - 读取程序选项组中的所有选项，包括类型、当前值、默认值和描述
• get_property - 读取属性映射中某地址存储的值
• import_file - 从磁盘将二进制文件导入当前Ghidra项目并打开
• list_open_programs - 列出已打开的程序

项目组织

• create_folder - 在项目中创建文件夹
• delete_file - 从项目中删除文件
• delete_project - 删除一个Ghidra项目
• list_projects - 列出可用的Ghidra项目
• move_file - 将文件移动到另一个项目文件夹
• move_folder - 将文件夹移动到另一个位置
• project_info - 获取详细项目信息，包括正在运行的工具和打开的程序

无头项目与程序生命周期

可在独立无头服务器（GhidraMCPHeadlessServer）上使用。

• archive_project - 将当前打开的项目归档为Ghidra原生.gar文件
• checkin_program - 将打开的程序以新版本形式签入到共享Ghidra服务器
• close_project - 关闭当前打开的项目
• create_project - 创建一个新的Ghidra项目
• export_program - 将打开的程序或项目中的程序导出为Ghidra Zip文件（.gzf）
• get_project_info - 获取当前打开项目的信息
• import_program - 将Ghidra Zip文件（.gzf）导入当前打开的项目，作为target_folder下的新DomainFile（默认'/'）
• load_program - 将二进制文件加载到无头服务器进行分析
• load_program_from_project - 从Ghidra项目加载程序（无头模式）
• open_project - 打开一个现有的Ghidra项目（.gpr文件或目录）
• restore_project - 将Ghidra .gar归档恢复为parent_dir/project_name处的新磁盘项目
• - 检查无头服务器连接状态

列表与枚举

• list_bookmarks - 列出书签
• list_calling_conventions - 列出可用的调用约定
• list_classes - 列出命名空间/类名
• list_data_items - 列出已定义的数据
• list_data_items_by_xrefs - 按交叉引用数排序列出数据
• list_exports - 列出导出的符号
• list_external_locations - 列出外部位置
• list_functions - 列出带地址的函数
• list_functions_enhanced - 列出带元数据的函数
• list_globals - 列出全局变量
• list_imports - 列出导入的符号
• list_methods - 列出所有函数名称，支持分页
• list_namespaces - 列出所有命名空间

上下文与查找

• get_current_address - 获取光标地址（仅GUI）
• get_current_function - 获取光标处的函数（仅GUI）
• get_current_selection - 获取CodeBrowser列表中高亮显示的地址范围（仅GUI）
• get_entry_points - 获取程序入口点
• get_enum_values - 获取枚举值
• get_external_location - 获取外部位置详情
• get_full_call_graph - 获取完整调用图
• get_function_by_address - 获取地址处的函数
• get_function_call_graph - 获取调用图
• get_function_callees - 获取被调用的函数
• get_function_callers - 获取调用函数
• get_function_count - 返回已加载程序中的函数数量
• get_function_jump_targets - 获取跳转目标

搜索

• find_similar_functions - 查找相似函数
• search_byte_patterns - 搜索字节模式
• search_data_types - 搜索数据类型
• search_functions - 按名称搜索函数
• search_functions_enhanced - 高级函数搜索
• search_strings - 按正则表达式/子串模式搜索已定义的字符串

反编译与反汇编

• decompile_function - 反编译函数
• disassemble_bytes - 反汇编字节范围
• disassemble_function - 反汇编函数
• force_decompile - 强制重新反编译

函数标签、变量与属性

• add_function_tag - 为函数附加一个或多个标签
• batch_add_function_tags - 在一次事务中为多个函数附加标签
• batch_remove_function_tags - 在一次事务中从多个函数分离标签
• clear_flow_and_repair - 在种子范围上运行Ghidra的GUI“清除流程并修复”操作：清除从种子可达的指令流，然后修复函数体并重新反汇编保留的流程（ClearFlowAndRepairCmd，参数clear_data=false, clear_labels=false, repair=true）
• create_function_tag - 创建一个程序级函数标签定义，带有可选注释
• delete_function_tag - 删除一个程序级函数标签定义
• get_function_tags - 列出分配给特定函数的所有标签
• list_class_members - 列出C++类的成员函数
• list_function_tags - 列出所有程序级函数标签定义及其使用计数
• remove_function_tag - 从函数分离一个或多个标签
• search_functions_by_tag - 列出所有附加了指定标签的函数
• set_decompiler_variable_type - 按名称设置反编译器（高级）变量或参数类型

交叉引用

• add_memory_reference - 创建两个内存地址之间的用户定义交叉引用，自动分析器无法推断（运行时填充的指针表、虚函数表、后期绑定的函数指针、未命中的跳转/开关表）
• get_bulk_xrefs - 获取多个地址的交叉引用
• get_function_xrefs - 获取函数交叉引用
• get_xrefs_from - 获取从地址出发的引用
• get_xrefs_to - 获取指向地址的引用
• remove_reference - 移除从一个地址到另一个地址的内存交叉引用——与add_memory_reference相反

数据类型与结构

• add_struct_field - 添加结构体字段
• analyze_global_completeness - 在预算0-100范围内对全局变量的文档完整性评分——与analyze_function_completeness类似的数据地址版本
• apply_data_type - 应用数据类型
• audit_global - 审计全局变量的文档状态
• audit_globals_in_function - 一次调用审计函数内引用的所有全局变量
• batch_set_variable_types - 设置多个变量类型
• clone_data_type - 克隆数据类型
• create_array_type - 创建数组类型
• create_data_type_category - 创建数据类型类别
• create_enum - 创建枚举
• create_function_signature - 创建函数签名类型
• create_pointer_type - 创建指针类型
• - 创建结构体

重命名与标签

• batch_create_labels - 创建多个标签
• batch_delete_labels - 删除多个标签
• batch_rename_function_components - 批量重命名函数组件
• create_label - 创建标签
• delete_label - 在地址处删除标签
• rename_data - 重命名数据符号
• rename_external_location - 重命名外部位置
• rename_function - 按名称重命名函数
• rename_function_by_address - 按地址重命名函数
• rename_global_variable - 重命名全局变量
• rename_label - 重命名标签
• rename_or_label - 重命名或创建标签
• rename_variable - 重命名函数中的变量

注释与书签

• batch_set_comments - 设置多个注释
• clear_function_comments - 清除函数的所有注释
• delete_bookmark - 删除书签
• get_comment - 获取任意地址（包括数据地址）的列表注释（plate/pre/eol/post/repeatable），与get_plate_comment不同，后者需要函数
• get_plate_comment - 获取板块注释
• set_bookmark - 设置书签
• set_comment - 在任意地址（包括数据地址）设置指定类型（plate/pre/eol/post/repeatable）的列表注释
• set_decompiler_comment - 设置前置注释（PRE_COMMENT）
• set_disassembly_comment - 设置行尾注释（EOL_COMMENT）
• set_plate_comment - 设置板块注释

分析

• analyze_api_call_chains - 分析API调用链
• analyze_call_graph - 分析函数调用图模式
• analyze_control_flow - 分析控制流
• analyze_data_region - 分析数据区域
• analyze_dataflow - 跟踪函数中的值传播（PCode图，前向/后向）
• analyze_for_documentation - 复合逆向工程文档分析（反编译+分类+变量+完整性）
• analyze_function_complete - 全面的单次调用函数分析
• analyze_function_completeness - 分析文档完整性
• analyze_struct_field_usage - 分析结构体字段使用情况
• apply_data_classification - 应用数据分类
• batch_analyze_completeness - 批量分析多个函数的完整性
• batch_apply_documentation - 一次调用为函数应用所有文档

跨二进制文档与归档

• archive_ingest_function - 将单个函数的文档摄入到跨版本归档中（bsim Postgres上的re_kb.functions）
• archive_ingest_program - 批量将程序中每个函数摄入到跨版本文档归档中
• batch_string_anchor_report - 源文件字符串及其FUN_*函数的报告
• bulk_fuzzy_match - 批量跨二进制函数匹配
• find_similar_functions_fuzzy - 跨二进制模糊函数匹配
• merge_program_documentation - 批量合并：将来自一个程序的所有逆向工程文档（函数名称、签名、板块注释、指令注释（EOL/PRE/POST）、非默认标签和全局符号）复制到另一个程序的匹配地址处

实用工具与文档传输

• apply_function_documentation - 应用函数文档
• check_connection - 健康检查端点
• compare_programs_documentation - 比较程序间的文档
• convert_number - 在进制之间转换数字
• diff_functions - 比较两个函数的差异
• find_undocumented_by_string - 查找引用字符串的未归档函数
• get_bulk_function_hashes - 获取批量函数哈希
• get_function_documentation - 导出函数文档
• get_function_hash - 获取函数哈希
• get_function_signature - 获取函数特征签名
• get_metadata - 获取程序元数据
• get_version - 获取插件版本
• health - 无头服务器的健康检查端点

仿真

• emulate_function - 使用受控的寄存器/内存输入仿真单个函数
• emulate_hash_batch - 暴力破解API哈希解析

脚本

• run_ghidra_script - 运行脚本并捕获输出
• run_script_inline - 运行内联脚本代码

Ghidra服务器与版本控制

• server_admin_set_permissions - 设置仓库的用户权限
• server_admin_terminate_all_checkouts - 递归终止文件夹中的所有签出
• server_admin_terminate_checkout - 终止单个文件上的所有签出
• server_admin_users - 列出服务器上的所有用户
• server_authenticate - 注册服务器凭据以进行编程身份验证
• server_checkouts - 列出文件夹中所有已签出的文件，包括服务器端签出
• server_connect - 连接到Ghidra服务器
• server_disconnect - 断开与Ghidra服务器的连接
• server_repositories - 列出已连接服务器上的仓库
• server_repository_create - 在服务器上创建新仓库
• server_repository_file - 从服务器仓库获取文件信息
• server_repository_files - 列出服务器仓库文件夹中的文件

调试器（Ghidra TraceRmi — 仅GUI）

在Windows主机上，如果桥接的WinDbg调试器代理处于活动状态（GHIDRA_DEBUGGER_URL），冲突的名称将获得_2后缀（例如debugger_status_2）。

• debugger_dynamic_to_static - 将当前跟踪中的运行时动态地址转换回静态Ghidra程序地址
• debugger_interrupt - 中断（中断进入）正在运行的目标
• debugger_launch - 通过Ghidra的Trace RMI调试器启动器启动可执行文件
• debugger_launch_offers - 列出当前程序可用的调试器启动/附加选项
• debugger_list_breakpoints - 列出当前跟踪中的所有断点
• debugger_modules - 列出调试进程中加载的模块（DLL/EXE）
• debugger_read_memory - 从调试进程读取内存
• debugger_registers - 从当前调试跟踪快照读取CPU寄存器
• debugger_remove_breakpoint - 移除某地址处的断点
• debugger_resume - 恢复调试进程的执行
• debugger_set_breakpoint - 在跟踪中的地址处设置软件执行断点
• debugger_stack_trace - 获取当前线程的调用堆栈回溯

系统

• prompt_policy - 临时启用、禁用或查询范围自动化提示处理

桥接静态工具在Python桥接器自身中定义（实例发现、工具组管理）；即使在Ghidra连接之前也始终可用。当GHIDRA_DEBUGGER_URL指向独立调试服务器时，该桥接器还会代理22个debugger_* WinDbg工具。

• check_tools - 报告当前已注册且可调用的工具
• connect_instance - 将桥接器连接到特定的Ghidra实例
• import_file - 将磁盘上的二进制文件导入当前项目并打开
• list_instances - 发现正在运行的Ghidra MCP实例（UDS + TCP端口扫描）
• list_tool_groups - 列出工具组及其加载状态
• load_tool_group - 向MCP客户端注册工具组的动态工具
• search_tools - 按关键字搜索全部工具目录
• unload_tool_group - 注销工具组的动态工具

请参见CHANGELOG.md了解版本历史。

🏗️ 架构```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### 组件

- **python/bridge_mcp_ghidra/** — Python MCP 服务器包（以 `ghidra-mcp-bridge` wheel 形式分发；`bridge-mcp-ghidra` 控制台脚本），将 MCP 协议转换为 HTTP 调用（225 个目录条目）
- **GhidraMCP.jar** — Ghidra 插件，通过 HTTP 暴露分析能力（175 个 GUI 端点）
- **GhidraMCPHeadlessServer** — 独立无头服务器——183 个端点，无需 GUI
- **ghidra_scripts/** — 常用任务自动化脚本集合

## 🔧 开发

### 从源代码构建```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

目前权威的构建系统是Maven。tools.setup、VS Code任务以及文档化的部署流程都通过pom.xml构建，并将产物写入target/。build.gradle仍然保留在仓库中，作为直接使用Ghidra/Gradle用户的手动回退方案，但它不是主要路径。

命令参考

大多数命令都接受以下通用标志：

部署测试层级是可选加入的，因为基准测试层级可以在当前Ghidra项目中导入/重置Benchmark.dll和BenchmarkDebug.exe。在发布之前使用--test release，或者当您希望机器上的每次部署都运行实时基准回归时，在本地.env中设置GHIDRA_MCP_DEPLOY_TESTS=release。请参阅测试与发布回归。```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### 项目结构```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

库依赖

编译前，必须将 Ghidra JAR 安装到本地 Maven 仓库（~/.m2/repository）。 这是每台机器的一次性设置，并且在您的 Ghidra 版本更改时需要重新设置。 -Deploy 现在默认自动安装这些依赖。

该工具强制要求以下版本一致：

• pom.xml（ghidra.version）
• --ghidra-path 的版本段（例如 ghidra_12.1.2_PUBLIC）

如果它们不匹配，部署将快速失败并给出明确的错误信息。

故障排除：版本不匹配

如果遇到版本不匹配错误，请对齐两个值：

1. pom.xml → ghidra.version
2. --ghidra-path 的版本段（ghidra_X.Y.Z_PUBLIC）

然后重新运行：```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

输入:```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

必需的库（14个JAR包，约37MB）：

注意：库不包含在仓库中（参见 .gitignore）。在构建之前，您必须从您的 Ghidra 安装中安装它们。

自动化入口点：

• python -m tools.setup 是受支持的设置/构建/部署/版本控制接口
• 直接使用 ensure-prereqs、build、deploy、preflight、clean-all 和 bump-version
• 这些命令当前使用 Maven 作为规范的 Java 构建后端

开发功能

• 自动部署：版本感知部署脚本
• 批量操作：将API调用减少93%
• 原子事务：全有或全无语义
• 全面日志记录：调试和追踪功能

📚 文档

核心文档

• 文档索引 - 完整文档导航
• 项目结构 - 项目组织指南
• 测试与发布回归 - 本地测试、CI、实时Ghidra回归及发布门控
• 命名规范 - 代码命名标准
• 匈牙利命名法 - 变量命名指南

AI工作流提示

• 函数文档 V5 — 主要工作流：7步流程，包含匈牙利命名法、类型审计和验证评分
• 批量文档 V5 — 用于多函数处理的并行子代理分发
• 孤立代码发现 — 自动扫描器，用于发现未识别的函数
• 数据类型调查 — 系统化的结构发现
• 跨版本匹配 — 基于哈希的函数匹配
• 快速入门提示 — 简化版初学者工作流
• 所有提示 — 完整提示索引

发布历史

• 完整变更日志 - 所有版本发布说明
• 发布说明 - 详细发布文档

🐳 无头服务器（Docker）

GhidraMCP 包含一个无头服务器模式，用于在无需Ghidra GUI的情况下进行自动化分析。

Docker快速开始```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### 无头 API 工作流```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

关键无头端点

配置

Docker 环境变量：

• GHIDRA_MCP_PORT - 服务器端口（默认：8089）
• GHIDRA_MCP_BIND_ADDRESS - 绑定地址（Docker 中默认：0.0.0.0）
• JAVA_OPTS - JVM 选项（默认：-Xmx4g -XX:+UseG1GC）

🤝 贡献

详细贡献指南请参阅 CONTRIBUTING.md。

快速开始

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 构建并测试您的更改（mvn clean package assembly:single -DskipTests 或 GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension）
4. 根据需要更新文档
5. 提交更改（git commit -m 'Add amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 发起 Pull Request

📄 许可证

本项目基于 Apache License 2.0 许可 - 详情请参阅 LICENSE 文件。

🏆 生产状态

版本历史和发布说明请参阅 CHANGELOG.md。

🙏 致谢

本项目最初源自 2025 年 8 月的 LaurieWired/GhidraMCP，此后进行了大量重写和扩展。我们感谢 LaurieWired 的原创工作作为起点。许可证归属请参阅 NOTICE。

👥 贡献者

本项目受益于热忱贡献者的工作：

核心贡献者

@heeen — 重大贡献包括：

• 模糊函数匹配和结构化差异比较，用于跨二进制对比 (#13)
• 脚本执行改进和错误修复 (#12)
• 新增 API 端点：save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• 架构愿景：注解驱动设计、UDS 传输、Python 桥接优化提案

@huehuehuehueing — 重大贡献包括：

• 地址空间前缀支持 — 添加了 <space>:<hex> 语法（例如 mem:1000, code:ff00）到整个端点覆盖面的地址解析中，解锁了嵌入式固件等多空间目标 (#84, 关闭 #65)

• 可选的 program 参数 + 必需参数模式修复 — 使每个端点上的 program 变为可选，并合理回退到 currentProgram，同时修复了目录中继承的几个必需与可选模式错误 (#92)

• 发起了 #44（数据类型/枚举工具）— 这个议题推动了 v5.0 的枚举和结构强制执行层

• Ghidra 团队 - 感谢这个出色的逆向工程平台

• 模型上下文协议 - 感谢标准化的 AI 集成框架

• 贡献者 - 感谢测试、反馈和改进

🔗 相关项目

• re-universe — 用于大规模二进制相似性分析的 Ghidra BSim PostgreSQL 平台。与 GhidraMCP 完美结合，用于 AI 驱动的逆向工程工作流。
• cheat-engine-server-python — 用于动态内存分析和调试的 MCP 服务器。

已准备好进行生产部署，具备企业级可靠性和全面的二进制分析能力。