bethington/ghidra-mcp · 上手攻略
- 仓库：bethington/ghidra-mcp
- 链接：https://github.com/bethington/ghidra-mcp
- 分类：skill
- 作者：Tom
- 更新：2026-07-22
是什么
ghidra-mcp 是一个生产级 MCP（Model Context Protocol）服务器，将 NSA 开源的 Ghidra 反编译引擎以 269 个 MCP 工具的形式暴露给 AI Agent，供其进行 AI 驱动的二进制逆向工程。与大多数 Ghidra MCP 实现只提供几个只读工具不同，这是一个由真实逆向工程师日常使用的完整方案——支持完整的写操作（重命名、类型标注、注释、结构体创建）、P-code 仿真、17 个 Java 调试端点 + 22 个 Python 桥接工具、以及原子事务与批量操作。
解决什么问题
- AI Agent 无法操控二进制：传统上 AI 只能读取反编译结果，ghidra-mcp 提供了完整的写入能力，让 Agent 能主动修改函数名、添加类型、写入注释。
- 工具数量太少：大多数 Ghidra MCP 只有 10–80 个工具，且多为只读。ghidra-mcp 提供 269 个，覆盖函数分析、数据流分析、P-code 仿真、实时调试、结构体发现、批处理等全流程。
- 命名规范无法执行：v5.0 将命名规范（PascalCase、动词前缀等）内置到工具层，AI 生成的代码自动符合团队规范，不再需要每次 prompt 附带风格指南。
- 生产环境可靠性不足：缺乏原子事务、批量操作（减少 93% API 调用）、超时配置——ghidra-mcp 针对生产场景做了完整加固。
快速安装
前置依赖
- Java 21 LTS（推荐 OpenJDK）
- Apache Maven 3.9+
- Ghidra 12.1.2（或兼容版本）
- Python 3.10+ + uv（推荐）或 pip + venv
⚠️ Ghidra 12.1.2 客户端需要 Ghidra Server 为 12.1 / 12.0.5 或更高版本。Jython 扩展（运行
.py脚本）需在 Ghidra 中手动安装：File > Install Extensions，重启 Ghidra。
通用安装流程
# 1. 克隆仓库
git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp
# 2. 环境预检（推荐）
python -m tools.setup preflight --ghidra-path "~/ghidra_12.1.2_PUBLIC"
# 3. 安装依赖 + 构建 + 部署（三步走）
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"
ensure-prereqs 会把 Ghidra JAR 安装到本地 Maven 仓库（~/.m2/repository）。deploy 会：
- 构建 GhidraMCP-.zip
- 解压扩展到 ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/（Linux）或 ~/Library/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/（macOS）
- 安装 Python 依赖
- 重启 Ghidra 并等待 MCP 健康检查
启动 MCP 服务器
# 在已运行的 Ghidra GUI 中
# 菜单：Tools > GhidraMCP > Start MCP Server
# 或命令行（headless 模式）
uv run bridge-mcp-ghidra
配置 AI 客户端（以 Cursor 为例）
{
"mcpServers": {
"ghidra": {
"command": "uv",
"args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"]
}
}
}
HTTP 传输（供 Web 客户端）
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081
对应 MCP 配置：
{
"mcpServers": {
"ghidra-mcp-http": {
"url": "http://127.0.0.1:8081/mcp"
}
}
}
其他平台快速命令
| 平台 | 特殊说明 |
|---|---|
| Linux（Debian/Ubuntu） | 用 uv run 避免 PEP 668 externally-managed-environment 错误 |
| macOS（Homebrew） | brew install openjdk@21 maven python ghidra，Ghidra 路径 /opt/homebrew/opt/ghidra/libexec |
| Arch Linux（AUR） | yay -S ghidra-mcp（社区包） |
核心用法
MCP 工具分类（共 269 个）
函数分析类：decompile、analyze_function_completeness（0–100% 评分）、find_orphaned_functions、get_call_graph、get_cross_references
数据流分析类：pc ode_graph_forward/backward（从任意变量/寄存器追踪数据传播）
结构体发现类：create_structure、create_union、create_enum、analyze_struct_fields
字符串处理类：search_strings（正则）、filter_string_quality、find_functions_by_string
内存操作类：read_memory、search_byte_pattern、detect_array_boundaries
跨二进制文档传递：sha256_function_hash_match（自动将文档同步到同函数的其他二进制版本）
P-code 仿真：emulate_function（用 Ghidra EmulatorHelper 隔离运行任意函数，毫秒级暴力破解 API hash）
实时调试（17 Java + 22 Python 桥接）：attach_debugger、set_breakpoint、step、get_registers、read_memory_trace
脚本管理：create_script、run_script、update_script、delete_script（全链路 MCP 管理 Ghidra 脚本）
批量操作：batch_rename、batch_comment、batch_set_type（93% API 调用减少）
项目与版本控制：create_project、manage_files、ghidra_server_checkin/checkout
约定执行层（v5.0 核心特性）
| 级别 | 行为 | 示例 |
|---|---|---|
| Auto-fix | 自动静默修复 | uint32 的 count 字段 → 保存时自动加 dw 前缀为 dwCount |
| Warn | 放行但返回警告 | processData → "name should be PascalCase with verb: ProcessData" |
| Reject | 拒绝并解释 | undefined → undefined type → "no-op rejected, type unchanged" |
这意味着 AI Agent 生成的重命名、类型标注、注释天然符合团队规范，无需在 prompt 中重复风格指南。
函数文档工作流 V5（7步）
analyze_function_completeness获取评分- 匈牙利命名法检查
- 类型审计
- 注释质量分级（结构化注释 plate comments）
create_function_documentation写入文档- 验证评分提升
- 提交审查
典型适用场景
| 场景 | 关键工具 |
|---|---|
| 新binary 快速逆向 | find_orphaned_functions + decompile + analyze_function_completeness |
| 结构体重建 | create_structure + analyze_struct_fields + pc ode_graph_forward |
| 恶意软件调试 | attach_debugger + set_breakpoint + step + read_memory |
| API hash 破解 | emulate_function + brute_force_api_hash（毫秒级） |
| 批量逆向文档 | batch_rename + batch_comment + batch_set_type |
| 跨版本同步文档 | sha256_function_hash_match |
| 找二进制间差异 | cross_version_match + get_call_graph_diff |
坑与注意
- Python 脚本需要 Jython 扩展：Ghidra 12.1.2 的
.py脚本需在 Ghidra 中 File > Install Extensions 安装 Jython，重启生效。Java 脚本则开箱即用。 - Ghidra Server 版本匹配：Ghidra 12.1.2 客户端连接 Server 时，Server 必须是 12.1 / 12.0.5 或更高。
- HTTP 传输的 CORS：SSE/HTTP 模式下 loopback（任意端口）始终允许，bind host 和
GHIDRA_MCP_ALLOWED_HOSTS环境变量列出的 host 也允许。 - Lazy 模式慎用：
--lazy模式下只加载 listing、function、program 三个默认工具组，部分 MCP 客户端（如 Claude Code）不支持tools/list_changed，会看到不完整的工具列表。 - Maven 构建备用：
python -m tools.setup build底层调用 Maven；如有特殊需求可手动mvn clean package assembly:single -DskipTests（需提前把 Ghidra deps 装入本地.m2）。
与同类对比
| 特性 | ghidra-mcp | 其他 Ghidra MCP 实现 |
|---|---|---|
| 工具数量 | 269 | 通常 10–80 |
| 写操作 | ✅ 完整 | ❌ 或极有限 |
| P-code 仿真 | ✅ | ❌ |
| 实时调试 | ✅ 17 Java + 22 Python 端点 | ❌ 或部分 |
| 命名约定强制 | ✅ Auto-fix/Warn/Reject 三级 | ❌ |
| 批量操作 | ✅ 93% API 调用减少 | ❌ |
| 约定内置工具层 | ✅ v5.0 | ❌ |
| Headless + Docker | ✅ | 部分 |
| Ghidra Server 集成 | ✅ | ❌ |
一句话结论
ghidra-mcp 是目前最完整的 Ghidra MCP 实现——269 个工具覆盖逆向全流程，v5.0 将命名规范内置到工具层，让 AI Agent 生成的逆向成果天然符合团队标准，是二进制安全研究者和 AI 安全工具开发者的必备基础设施。