3.1 架构与安装

3.1 架构与安装

本节摘要：本节把 GhidraMCP 从「一个名词」变成「本机跑着的服务」。先拆 2.0 版架构：客户端（VS Code / Claude Code 等）经 MCP 协议连到 Python MCP 桥，桥再经 HTTP（默认端口 8080）连到 Ghidra 里的 Java 插件——2.0 起插件直接内置 HTTP server，Ghidra 侧不再需要旧版的 Python 桥接脚本；headless 场景则由 PyGhidra 驱动，要求 Python 3.10~3.13。然后是三步安装：取扩展、装进 Ghidra、装客户端桥；配 stdio 与 streamable-http 两种传输的选型与配置形态。再对照能力清单（列函数、反编译、重命名、xref、注释、段查看）把它映射回第 01 章的手艺动作。最后过安全注意（端口暴露、工程写权、样本敏感度）与五条常见故障排查。所有命令为写法示意，以官方仓库 README 为准。

学习目标

• 画出三层架构图并说出每层的进程归属。
• 说出 1.x 与 2.0 在架构上的差别及安装体验变化。
• 完成三步安装并让 8080 端口出现服务。
• 按场景选择 stdio 或 streamable-http 传输并写出配置。
• 把能力清单映射回第 1.2 节的走查五步。
• 记住三条安全注意：端口、写权、样本敏感度。

一、GhidraMCP 2.0 的架构

版本背景（社区口径，2026-10）：GhidraMCP 约 1.1 万 stars、Apache-2.0；2.0 于 2026-10-10 发布，适配 Ghidra 12.1.4。相对 1.x 的变化先用一张表看清：

┌─────────────────────┐   MCP（stdio / streamable-http）  ┌──────────────────┐
│ MCP 客户端           │ ────────────────────────────────▶│ Python MCP 桥     │
│ VS Code、Claude Code │ ◀──────────────────────────────── │ （uvx / pip 安装） │
└─────────────────────┘         工具调用与结果              └────────┬─────────┘
                                                                     │ HTTP :8080
                                                                     ▼
                                                          ┌────────────────────┐
                                                          │ Ghidra             │
                                                          │ Java 插件内置 server│
                                                          │ GUI 工程 / headless │
                                                          └────────────────────┘
​

分层的意义：模型只见 MCP 工具描述（列函数、反编译……），不关心底下是 GUI 还是 headless；换 Ghidra 版本、换客户端，中间的桥保持稳定。「移除 Ghidra 侧 Python 桥接层」的直接好处是少一个易错环节——旧版最常见的安装故障（桥脚本没跑、版本不匹配）整类消失。

二、三步安装

# bash —— 安装 GhidraMCP（三步，写法示意，以官方仓库 README 为准）
# 步骤一：从官方仓库 Releases 取 2.0 发行包，得到扩展 zip
# 步骤二：Ghidra 菜单 File - Install Extensions - 加号选 zip - 勾选启用 - 重启 Ghidra
# 步骤三：安装并启动 Python MCP 桥（二选一）
uvx ghidra-mcp
# 或：pip install ghidra-mcp && ghidra-mcp
​

三步各自的自检：步骤二重启后，插件出现在插件列表且 CodeBrowser 状态可见服务已起（以插件界面提示为准）；步骤三终端不报错即桥在等待连接；端到端自检在 3.2 节客户端接上后做——让模型列一次函数。

前置核对两条：Ghidra 版本与 GhidraMCP 版本要匹配（2.0 对应 Ghidra 12.1.4，随官方更新而变，以发行说明为准）；Java 侧就绪（第 1.1 节已装）。headless 用法（不点开 GUI）在 3.3 节展开。

三、两种传输：stdio 与 streamable-http

两种传输的配置形态示意（字段名以官方文档为准）：

# mcp_stdio.json —— stdio 传输：客户端自己拉起桥（示意）
{
  "servers": {
    "ghidra": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ghidra-mcp"]
    }
  }
}
​

# mcp_http.json —— streamable-http 传输：桥常驻，客户端连 URL（示意）
{
  "servers": {
    "ghidra": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
​

选型经验：本机一台机器全搞定就用 stdio；团队共享一个 Ghidra 实例、多人多个客户端连同一个工程时，streamable-http 才有价值——此时 8080 端口等于把工程操作权暴露到网络上，务必放在受信网段。

四、能力清单：映射回手艺

对照第 1.2 节走查五步：入口定位（列函数 + xref）、字符串锚点（段与数据查看）、结构对照（反编译）、常量计算（模型算、人核）、落库固化（重命名 + 注释）——除了「人裁决」，全部能力都在清单里。复核动作一列是刻意加的：模型每动一次手，你都有一个对应的检查点。

五、安全注意：三条边界

1. 端口即权限：8080 上的服务能读工程、能改名——暴露到不受信网络等于交出工程写权。跨机场景限定受信网段，必要时改端口（以官方文档为准）。
2. 写权即风险：模型的重命名与注释直接落工程（第 1.2 节的落库理念被复用了）。落库前的核对纪律见 3.2 节；批量动作必须走 3.3 节的「建议、复核、回写」三段流程。
3. 样本敏感度：反编译文本会流经桥与模型服务。敏感样本换本地模型（第 4.2 节），或干脆退回纯工具流（第 01~02 章）。

六、安装自检与常见故障

# bash —— 连通性自检（写法示意）：确认桥在、端口在
claude mcp list                 # 或客户端的等价命令：ghidra 应为已连接
netstat -ano | findstr 8080     # Windows 查端口；Linux 用 ss -ltnp | grep 8080
​

本节要点回顾

• 2.0 架构三层：MCP 客户端、Python 桥、Ghidra 内置 HTTP server；Ghidra 侧桥接层已成历史，安装故障少一整类。
• 三步安装：取扩展、装扩展、装桥；版本适配以发行说明为准。
• 传输选型：单机 stdio，跨机 streamable-http（端口即权限，限受信网段）。
• 能力清单六项映射走查五步，每项都配了人的复核动作。
• 三条边界：端口即权限、写权即风险、样本敏感度决定模型选型。

服务起来了，还没人跟它说话。下一节把 VS Code 与 Claude Code 两个客户端接上，完整走一遍「列函数、反编译、重命名、追引用」的对话式逆向。