Ghidra MCP 快速上手教程：从安装到反编译第一个函数，10分钟搭建AI逆向工程环境-迪斯科星球

Ghidra MCP 快速上手教程：从安装到反编译第一个函数，10分钟搭建AI逆向工程环境

【免费下载链接】ghidra-mcpGhidra MCP Server — 200+ MCP tools for AI-powered reverse engineering. GUI plugin + headless server, lazy tool loading, convention enforcement, batch operations, Ghidra Server integration, and Docker deployment.项目地址: https://gitcode.com/gh_mirrors/ghi/ghidra-mcp

Ghidra MCP Server是一个把 Ghidra 逆向工程能力接入 AI 客户端的 MCP（Model Context Protocol）服务器，内置253 个 MCP 工具，支持 GUI 插件、无头服务器和 Docker 部署。本教程带你用约 10 分钟完成 Ghidra MCP 安装，并让 AI 反编译出你的第一个函数。

一、Ghidra MCP 是什么？为什么值得装？

Ghidra MCP 由两部分组成，理解架构能让你少走弯路：

组件	位置	作用
Ghidra 插件（Java）	src/main/java/com/xebyte/	在 Ghidra 内部启动 HTTP 服务器（默认`127.0.0.1:8089`），暴露 239 个端点
MCP 桥接（Python）	python/bridge_mcp_ghidra/	把 MCP 协议翻译成对 Ghidra 的 HTTP 调用，AI 客户端通过它驱动 Ghidra
无头服务器（Java）	src/main/java/com/xebyte/headless/	不需要 Ghidra GUI，适合 Docker / CI 自动化分析

它的核心卖点：

🧰253 个工具：反编译、重命名、类型标注、注释、结构体创建、P-code 模拟、动态调试，读写全覆盖
⚡批量操作：一次调用处理多个对象，API 调用量减少 93%
📜约定强制执行：命名规范（匈牙利表示法）内置在工具层，AI 每次输出风格一致
🐳Docker 就绪：无头模式可直接用于 CI/CD 流水线

二、安装前准备：确认 4 个依赖

Ghidra MCP 的安装速度取决于依赖是否齐全。打开终端逐项确认：

依赖	版本要求	说明
Java	21 LTS	推荐 OpenJDK
Maven	3.9+	构建后端（Gradle 也可，CI 使用 Maven）
Ghidra	12.1.3	官方逆向工程平台
Python	3.10+	推荐搭配 uv 管理虚拟环境

💡新手提示：Ubuntu/Debian 上直接pip install可能报externally-managed-environment错误（PEP 668），不要用--break-system-packages绕过，请改用uv或虚拟环境（详见第六节常见问题）。

三、一键安装：克隆仓库并部署插件

以下步骤来自 README.md 官方快速开始章节。

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/ghi/ghidra-mcp cd ghidra-mcp

第 2 步：环境预检（强烈建议）

preflight会验证 Python、构建工具、Ghidra 路径，不做任何修改，适合新手先跑一遍：

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

第 3 步：构建并部署到 Ghidra

# 安装 Ghidra JAR 依赖到本地 Maven 仓库（每台机器一次） python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.3_PUBLIC" # 构建插件 python -m tools.setup build # 部署：安装扩展、启动 Ghidra、等待 MCP 健康检查 python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.3_PUBLIC"

deploy命令会自动完成一整套工作：保存并关闭正在运行的 Ghidra 实例（如需要）→ 安装用户配置扩展 → 等待 MCP 健康检查通过 → 执行 schema 冒烟检查。整个过程无需手动干预。

⚠️版本一致性：工具会强制校验pom.xml中的ghidra.version与你--ghidra-path中的版本段（如ghidra_12.1.3_PUBLIC）一致，不一致会快速报错而不是静默构建出坏包。

macOS 用户可直接brew install openjdk@21 maven python ghidra，Ghidra 路径使用/opt/homebrew/opt/ghidra/libexec。

四、在 Ghidra 中启动 MCP 服务器

部署完成后，启动 Ghidra 并操作 CodeBrowser 窗口：

File > Configure > Configure All Plugins > GhidraMCP— 勾选启用插件
Tools > GhidraMCP > Start MCP Server— 启动服务器
服务器默认运行在http://127.0.0.1:8089/（端口可在Edit > Tool Options > GhidraMCP HTTP Server中修改）

验证是否成功：

curl http://127.0.0.1:8089/check_connection # 预期输出: "Connected: GhidraMCP plugin running with program '<name>'" curl http://127.0.0.1:8089/get_version

看到Connected字样，说明 Ghidra 侧已就绪。🎉

五、反编译第一个函数：接入 AI 客户端

Ghidra 侧只是后端，真正让 AI 驱动它的是 Python 桥接。运行方式：

uv run bridge-mcp-ghidra # 或: python -m bridge_mcp_ghidra

然后把你使用的 AI 客户端（Cursor、Claude Desktop 等）的 MCP 配置指向桥接。以 stdio 方式为例（.mcp.json）：

{ "mcpServers": { "ghidra-mcp": { "command": "/home/<you>/.local/bin/uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra", "--transport", "stdio"], "env": { "GHIDRA_MCP_URL": "http://127.0.0.1:8089" } } } }

⚠️最常见的坑：command必须写uv的绝对路径（用which uv查询），不能只写"uv"。GUI 启动的客户端继承的是系统 PATH 而非你的 shell PATH，找不到命令会报spawn uv ENOENT，且日志里没有任何线索。

让 AI 执行一次典型反编译

在 Ghidra 中打开一个二进制文件并运行Analysis > Auto Analyze，然后在 AI 客户端里直接提问，AI 会按顺序调用这些工具：

步骤	工具	作用
1	`get_metadata`	确认加载了哪个程序（架构、入口基址、函数数）
2	`list_methods`	分页枚举所有函数名，定位分析目标
3	`get_entry_points`	找到程序入口，作为分析起点
4	`decompile_function`	反编译函数为 C 伪代码（支持一次传多个函数）
5	`get_function_callers`/`get_function_callees`	沿调用图继续深入

例如对 AI 说："反编译入口函数，解释它调用了哪些 API"，AI 就会自动组合上述工具完成任务。这 4 个工具（get_metadata、list_methods、get_entry_points、decompile_function）恰好构成一个自足的只读最小集合——它们互相提供地址和名称，形成闭环。

📖 工具选择器search_tools可按关键词搜索全部 253 个工具，load_tool_group可动态加载未注册的工具组（如datatype、xref），桥接默认采用懒加载，避免一次性向 AI 塞入过多上下文。

六、进阶玩法：Docker 无头部署

如果你想在 CI 或服务器上批量分析二进制而不需要 GUI，Docker 是最快的路径。部署细节见 docker/README.md：

cd docker export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32) # 必填！ docker compose up -d --build # 验证 curl -H "Authorization: Bearer $GHIDRA_MCP_AUTH_TOKEN" http://localhost:8089/check_connection

这会拉起两个容器：ghidra-mcp（8089 端口，REST API）和ghidra-mcp-bridge（8081 端口，MCP over streamable-http）。无头模式的典型 API 工作流：

# 加载二进制 → 自动分析 → 列函数 → 反编译 curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program curl -X POST http://localhost:8089/run_analysis curl "http://localhost:8089/list_functions?limit=20" curl "http://localhost:8089/decompile_function?address=0x401000"

🔒安全提醒：服务器默认仅绑定127.0.0.1且无需认证，适合单用户开发机。一旦暴露到回环地址之外，必须先设置GHIDRA_MCP_AUTH_TOKEN，否则服务器会拒绝启动。

七、常见问题排查（新手高频 3 问）

现象	原因	解决
`Tools`菜单没有`GhidraMCP`	插件未启用或未安装	File > Install Extensions确认 GhidraMCP 已列出 → 在 Configure All Plugins 中勾选 →重启 Ghidra
客户端报`spawn uv ENOENT`	客户端用自身 PATH 找不到`uv`	配置中改用绝对路径，或运行`python -m tools.setup preflight`获取可粘贴的配置片段
服务器无响应 / Connection refused	服务器未启动或端口被占	确认已执行 Start MCP Server；`lsof -i :8089`（Linux/macOS）或`netstat -ano \\| findstr :8089`（Windows）查端口占用

更多诊断方法（含三层架构排查：Ghidra 插件 → 桥接 → 客户端会话）见 docs/connection-triage-guide.md。

八、下一步：让 AI 系统性地文档化你的二进制

装好环境只是开始。项目内置了一整套经过数百个真实函数打磨的 AI 工作流提示词，位于 docs/prompts/：

📄函数文档化 V5 工作流：FUNCTION_DOC_WORKFLOW_V5.md — 7 步标准流程：命名 → 原型 → 类型审计 → 注释 → 完整性评分验证
🚀快速入门提示词：QUICK_START_PROMPT.md — 简化版新手工作流
🔍孤儿代码发现：ORPHANED_CODE_DISCOVERY_WORKFLOW.md — 自动扫描未发现的函数
🧩数据类型调查：DATA_TYPE_INVESTIGATION_QUICK.md — 结构体发现与字段分析
📚 完整提示词索引：docs/prompts/README.md

一个典型的 V5 循环：调用analyze_for_documentation初始化 →rename_function+set_function_prototype并行改名定型 →rename_variables批量重命名变量 →batch_set_comments一次写完所有注释 → 最后用analyze_function_completeness拿到 0–100 分的文档完整性评分，扣掉可修复项再复检。

回顾本次旅程：约 10 分钟内，你完成了 Ghidra MCP 的克隆、构建、部署，启动了插件服务器，接入 AI 客户端并反编译了第一个函数。现在你可以继续深入：

完整 API 参考（253 个工具按分类列出）：README.md
项目结构与代码布局：docs/PROJECT_STRUCTURE.md
构建与版本管理命令全集：docs/MAVEN_VERSION_MANAGEMENT.md

💬 小提示：批量操作和约定强制执行是这套工具与"演示级" Ghidra MCP 的最大区别——工具层自带规范，AI 无需在每次提示词里重复风格指南。祝逆向愉快！🛠️

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析