内容
# Ghidra MCP 服务器
Ghidra 无头服务器，通过模型上下文协议（MCP）暴露，用于二进制分析，恶意软件逆向工程和 AI 助手。可以在本地或 Docker 中运行。
## 功能
- **32 个 MCP 工具** 用于二进制分析：反编译、函数列表、字符串搜索、交叉引用、字节模式搜索、恶意软件分析、RE 工具（CFG、调用图、指令搜索）和仿真
- **3 个仿真工具** — 模拟函数，自动处理调用约定，单步执行代码，读取寄存器和内存
- **5 个 MCP 资源** 用于浏览二进制元数据、函数、字符串和导入
- **多二进制支持** — 在单个 Ghidra 项目中同时分析多个二进制文件
- **恶意软件分析工具** — 熵分析（打包检测）、可疑 API 分类、节异常检测
- **代码模式** — 节省令牌的操作模式，仅暴露 2 个工具（`search` + `execute`）而不是全部 32 个，用于 LLM 高效使用
- **Ghidra 服务器** — 连接到共享的 Ghidra 服务器，进行协作逆向工程，带有检入/检出工作流
- **SSE 传输** — 作为 HTTP 服务器运行，带 `--transport sse`，用于网络可访问部署
- **Docker 或本地** — 在隔离容器或通过 stdio 传输直接在机器上运行
- **PyGhidra 3.0** — 通过进程内 JVM 直接访问 Ghidra Java API（无需 Ghidra 脚本）
## 快速入门
### Docker（推荐）
```bash
# 构建镜像
docker compose build
# 以完整模式运行（所有 32 个工具）
docker compose run --rm -i ghidra-mcp
# 以代码模式运行（2 个工具：search + execute，节省令牌）
docker compose run --rm -i ghidra-mcp --mode code
```
参见 [客户端配置](#客户端配置) 以设置 Claude Desktop、Claude Code、OpenCode 和 Continue.dev。
#### Apple Silicon
Docker 镜像在 arm64 上本地构建。由于 Ghidra 版本不包含预构建的 `linux_arm_64` 反编译器二进制文件，因此 Dockerfile 会在 `docker compose build` 期间自动从源代码构建反编译器（增加 ~2 分钟构建时间，无需额外配置）。如果遇到问题，可以通过取消注释 `docker-compose.yml` 中的 `platform: linux/amd64` 来强制 x86_64 模拟（由于 Rosetta/QEMU 较慢）。
### 本地（无 Docker）
#### 要求
- **Python 3.11+** — [python.org/downloads](https://www.python.org/downloads/)。在 Windows 上，安装时勾选“Add Python to PATH”。
- **Java 21+** （例如 OpenJDK 21）— `JAVA_HOME` 必须设置，`java` 必须在 PATH 上。
- **Linux/macOS:** `export JAVA_HOME=/path/to/jdk-21`（添加到 `~/.bashrc` 或 `~/.zshrc`）
- **Windows:** 通过系统属性 > 环境变量设置 `JAVA_HOME`（例如 `C:\Program Files\Eclipse Adoptium\jdk-21`）
- **[Ghidra 12.0.4](https://github.com/NationalSecurityAgency/ghidra/releases)** — 下载并提取（无需安装程序）。
- **`GHIDRA_INSTALL_DIR`** 环境变量，指向 Ghidra 安装目录。
- **Linux/macOS:** `export GHIDRA_INSTALL_DIR=/path/to/ghidra_12.0.4_PUBLIC`（添加到 `~/.bashrc` 或 `~/.zshrc`）
- **Windows:** 通过系统属性 > 环境变量或 `set GHIDRA_INSTALL_DIR=C:\ghidra\ghidra_12.0.4_PUBLIC` 在命令提示符中设置
#### 安装
**快速安装** （检查要求，创建虚拟环境，安装）：
```bash
# Linux/macOS
./scripts/install.sh
# Windows (PowerShell)
.\scripts\install.ps1
```
**手动安装：
```bash
python -m venv venv
# Linux/macOS:
source venv/bin/activate
# Windows (命令提示符):
venv\Scripts\activate
# Windows (PowerShell):
venv\Scripts\Activate.ps1
pip install -e .
```
#### 使用
```bash
# 激活虚拟环境（参见 Windows 命令的安装）
source venv/bin/activate
# 完整模式（默认）— 所有 32 个工具
ghidra-mcp
# 代码模式 — 2 个元工具（search + execute）
ghidra-mcp --mode code
# 自定义项目目录和名称
ghidra-mcp --project-dir ~/my-projects --project-name my_project
# Windows: ghidra-mcp --project-dir C:\Users\you\my-projects --project-name my_project
# SSE 传输（localhost:8080 上的 HTTP 服务器）
pip install -e ".[sse]"
ghidra-mcp --transport sse
# SSE 自定义主机和端口
ghidra-mcp --transport sse --host 0.0.0.0 --port 3000
```
参见 [客户端配置](#客户端配置) 以设置 Claude Desktop、Claude Code、OpenCode 和 Continue.dev。
## 客户端配置
> 所有示例均显示 **完整模式**。对于 **代码模式**，追加 `--mode code`（Docker：将在 args 数组中添加 `"--mode", "code"`；本地：将 `"--mode", "code"` 添加到 args 或命令）。
### Claude Desktop
配置文件：`claude_desktop_config.json`
**Docker：**
```json
{
"mcpServers": {
"ghidra": {
"command": "docker",
"args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
}
}
}
```
**本地：
```json
{
"mcpServers": {
"ghidra": {
"command": "/path/to/venv/bin/ghidra-mcp",
"env": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
}
}
}
}
```
> **注意：** 使用虚拟环境中 `ghidra-mcp` 的完整路径。如果 `GHIDRA_INSTALL_DIR` 已在 shell 配置文件中设置，可以省略 `env` 块。**Windows：** 使用 `C:\path\to\venv\Scripts\ghidra-mcp.exe` 作为命令，`GHIDRA_INSTALL_DIR` 使用 Windows 样式路径。
### Claude Code
**Docker — 通过 CLI：
```bash
claude mcp add ghidra -- docker compose -f /path/to/docker-compose.yml run --rm -i ghidra-mcp
```
**Docker — 通过项目配置** （`.mcp.json` 在项目根目录）：
```json
{
"mcpServers": {
"ghidra": {
"command": "docker",
"args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
}
}
}
```
**本地 — 通过 CLI：
```bash
claude mcp add ghidra --env GHIDRA_INSTALL_DIR=/path/to/ghidra_12.0.4_PUBLIC -- /path/to/venv/bin/ghidra-mcp
```
**本地 — 通过项目配置** （`.mcp.json`）：
```json
{
"mcpServers": {
"ghidra": {
"command": "/path/to/venv/bin/ghidra-mcp",
"env": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
}
}
}
}
```
> **注意：** 使用虚拟环境中 `ghidra-mcp` 的完整路径。如果 `GHIDRA_INSTALL_DIR` 已在 shell 配置文件中设置，可以省略 `env` 块和 `--env` 标志。**Windows：** 使用 `C:\path\to\venv\Scripts\ghidra-mcp.exe` 作为命令，`GHIDRA_INSTALL_DIR` 使用 Windows 样式路径。
### OpenCode
配置文件：`opencode.json`（项目根目录或 `~/.config/opencode/opencode.json`）
**Docker：**
```json
{
"mcp": {
"ghidra": {
"type": "local",
"command": ["docker", "compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"],
"enabled": true
}
}
}
```
**本地：
```json
{
"mcp": {
"ghidra": {
"type": "local",
"command": ["/path/to/venv/bin/ghidra-mcp"],
"environment": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
},
"enabled": true
}
}
}
```
> **注意：** 使用虚拟环境中 `ghidra-mcp` 的完整路径。如果 `GHIDRA_INSTALL_DIR` 已在 shell 配置文件中设置，可以省略 `"environment"` 块。**Windows：** 在命令数组中使用 `C:\path\to\venv\Scripts\ghidra-mcp.exe`，`GHIDRA_INSTALL_DIR` 使用 Windows 样式路径。
### Continue.dev
配置文件：`.continue/mcpServers/ghidra.json`
> **注意：** MCP 工具仅在 Continue 的 **Agent 模式** 中可用，而非 Chat 模式。
**Docker：**
```json
{
"mcpServers": [
{
"name": "Ghidra",
"type": "stdio",
"command": "docker",
"args": ["compose", "-f", "/path/to/docker-compose.yml", "run", "--rm", "-i", "ghidra-mcp"]
}
]
}
```
**本地：
```json
{
"mcpServers": [
{
"name": "Ghidra",
"type": "stdio",
"command": "/path/to/venv/bin/ghidra-mcp",
"env": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra_12.0.4_PUBLIC"
}
}
]
}
```
> **注意：** 使用虚拟环境中 `ghidra-mcp` 的完整路径。如果 `GHIDRA_INSTALL_DIR` 已在 shell 配置文件中设置，可以省略 `env` 块。**Windows：** 使用 `C:\path\to\venv\Scripts\ghidra-mcp.exe` 作为命令，`GHIDRA_INSTALL_DIR` 使用 Windows 样式路径。
## 服务器模式
服务器支持三种操作模式，可通过 `--mode` 标志选择：
| 模式 | 标志 | 已注册工具 | 用例 |
|------|------|-----------------|----------|
| **完整** | `--mode full`（默认） | 所有 32 个工具 + 5 个资源 | 直接工具访问，适用于探索和交互式使用 |
| **代码** | `--mode code` | 2 个工具（`search` + `execute`） | 节省令牌，适用于自动化管道和成本敏感的使用 |
| **脚本** | `--mode script` | 6 个工具（`search_api` + `get_class_info` + `execute_script` + 二进制管理） | 通过实时反射和 Python 代码执行直接访问 Ghidra Java API |
完整模式和代码模式提供相同的分析能力 — 代码模式通过动态调度程序路由调用，而不是单独注册每个工具。脚本模式更进一步，暴露原始 Ghidra Java API，用于自定义分析，而这些分析不受内置工具的覆盖。
## MCP 工具（完整模式）
### 项目管理
| 工具 | 描述 |
|------|-------------|
| `import_binary` | 导入二进制文件进行分析 |
| `upload_binary` | 通过 base64 编码数据上传二进制文件 |
| `list_binaries` | 列出所有导入的二进制文件 |
| `delete_binary` | 从项目中删除二进制文件 |
### 分析
| 工具 | 描述 |
|------|-------------|
| `list_functions` | 列出具有分页和名称过滤的函数 |
| `decompile_function` | 将函数反编译为 C 伪代码 |
| `rename_function` | 重命名函数 |
| `rename_variable` | 重命名函数内的变量（参数或局部变量） |
| `rename_label` | 重命名程序中的符号/标签 |
| `list_strings` | 列出已定义的字符串 |
| `search_strings` | 按子字符串或正则表达式搜索字符串 |
| `list_imports` | 列出导入的符号 |
| `list_exports` | 列出导出的符号 |
| `get_xrefs` | 获取到/从地址的交叉引用 |
| `search_bytes` | 搜索带有通配符的十六进制字节模式 |
| `get_memory_bytes` | 从地址读取原始字节 |
| `search_instructions` | 反汇编指令/操作数的正则表达式搜索 |
### 恶意软件分析
| 工具 | 描述 |
|------|-------------|
| `get_entropy` | 按节的香农熵，打包检测 |
| `detect_suspicious_apis` | 分类可疑导入（注入、持久化、加密、网络、反调试） |
| `get_sections` | 具有权限、熵和异常标志的节（W+X，不寻常的名称） |
### 高级分析
| 工具 | 描述 |
|------|-------------|
| `get_function_summary` | 丰富的函数元数据（参数、被调用者、调用者、字符串、复杂性），无需反编译 |
| `get_basic_blocks` | 具有指令和边的控制流图基本块 |
| `get_call_graph` | 具有 BFS 深度控制的函数调用图（被调用者/调用者/两者） |
### 仿真
使用 Ghidra 的 `EmulatorHelper` API 模拟函数。模拟器自动处理调用约定 — 参数根据函数的参数元数据放置在正确的寄存器或堆栈位置，返回值从适当的返回寄存器中提取。
| 工具 | 描述 |
|------|-------------|
| `emulate_function` | 模拟具有可选整数参数的函数，获取返回值 |
| `emulate_step` | 单步执行现有的模拟器会话，读取寄存器和内存 |
| `emulate_session_destroy` | 销毁模拟器会话并释放其资源 |
### 服务器连接
连接到共享的 Ghidra 服务器进行协作逆向工程。服务器打开的程序可供所有分析工具使用。支持具有独家锁定的检入/检出工作流。
| 工具 | 描述 |
|------|-------------|
| `connect_server` | 连接到 Ghidra 服务器（主机、端口、用户名、密码可选） |
| `disconnect_server` | 断开与服务器的连接，释放检出，清理 |
| `list_repositories` | 列出连接服务器上可用的存储库 |
| `list_server_files` | 列出服务器存储库中的文件和子文件夹 |
| `open_from_server` | 从服务器打开程序进行分析（可选检出） |
| `checkin_file` | 将更改检入到 Ghidra 服务器 |
#### 服务器工作流
```bash
# 1. 连接到 Ghidra 服务器
connect_server(host="ghidra.example.com", port=13100, username="analyst")
# 2. 浏览可用的存储库和文件
list_repositories()
list_server_files(repository_name="malware-lab")
# 3. 打开程序（检出进行编辑）
open_from_server(repository_name="malware-lab", file_path="/samples/trojan.exe", checkout=True)
# 4. 使用任何工具分析 — 反编译、重命名函数等
decompile_function(binary_name="trojan.exe", name_or_addr="main")
rename_function(binary_name="trojan.exe", old_name="FUN_00401000", new_name="decrypt_payload")
# 5. 将更改保存回服务器
checkin_file(binary_name="trojan.exe", comment="Identified decryption routine")
# 6. 完成后断开连接
disconnect_server()
```
#### 仿真工作流
典型的仿真工作流是：
1. **启动仿真** 使用 `emulate_function` — 设置模拟器，放置参数，运行直到函数返回或达到步数限制，并返回结果，包括返回值。
2. **交互式检查** （可选）使用 `emulate_step` — 在 `emulate_function` 创建会话后，可以单步执行剩余的执行，读取特定寄存器和内存区域。
3. **清理** 使用 `emulate_session_destroy` — 释放模拟器并释放资源。会话在二进制文件被删除或服务器关闭时也会自动清理。
#### 仿真示例
```bash
# 步骤 1：模拟具有参数的函数
emulate_function(binary_name="malware.exe", name_or_addr="decrypt_string", args=[0x00402000, 16])
# 返回：{
# "session_key": "malware.exe:decrypt_string",
# "return_value": 4198400,
# "steps_executed": 847,
# "hit_breakpoint": true,
# ...
# }
# 步骤 2：检查执行后的寄存器和内存
emulate_step(binary_name="malware.exe", name_or_addr="decrypt_string",
count=0, read_registers=["RAX", "RCX"],
read_memory=[{"address": "0x00402000", "size": 32}])
# 返回：{
# "registers": {"RAX": "0x401000", "RCX": "0x0"},
# "memory": [{"address": "0x00402000", "hex": "48656c6c6f..."}],
# ...
# }
# 步骤 3：清理
emulate_session_destroy(binary_name="malware.exe", name_or_addr="decrypt_string")
```
#### 仿真限制
- **外部调用**：如果模拟的函数调用导入/外部函数（例如 `printf`、`malloc`），则模拟将停止或产生未定义行为。只有自包含的函数才能正确模拟，而无需额外的存根。
- **架构支持**：支持 x86/x86-64（将哨兵返回值推送到堆栈）和 ARM/AARCH64（设置 LR 寄存器）。其他架构将引发错误。
- **仅限整数参数**：当前实现通过寄存器/堆栈写入处理整数参数。不支持浮点和结构体参数。
- **步数限制**：`max_steps` 参数（默认：10,000）可防止运行失控的模拟。
## MCP 资源
| URI | 描述 |
|-----|-------------|
| `ghidra://binaries` | 项目中的所有二进制文件 |
| `ghidra://binary/{name}/info` | 二进制元数据（架构、格式、哈希、入口点） |
| `ghidra://binary/{name}/functions` | 完整的函数列表 |
| `ghidra://binary/{name}/strings` | 所有已定义的字符串 |
| `ghidra://binary/{name}/imports` | 所有导入的符号 |
## 代码模式
代码模式是一种节省令牌的操作模式，它用 2 个元工具取代了所有 32 个单独的工具注册：`search` 和 `execute`。这大大减少了每次请求发送给 LLM 的工具模式数量，从而在保留完整分析能力的同时节省了令牌和成本。
### 激活
```bash
# Docker
docker compose run --rm -i ghidra-mcp --mode code
# 本地
ghidra-mcp --mode code
```
### 工具
#### `search(query?)`
搜索工具目录。返回工具名称、描述和完整的参数签名。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `query` | string | 否 | 子字符串，用于过滤工具名称和描述。如果省略，返回所有 32 个工具。 |
**示例 — 查找仿真工具：**
```
search(query="emulate")
# 返回：
# [
# {"tool": "emulate_function", "description": "模拟具有可选参数的函数...",
# "parameters": [{"name": "binary_name", "type": "string", "required": true}, ...]},
# {"tool": "emulate_step", ...},
# {"tool": "emulate_session_destroy", ...}
# ]
```
**示例 — 查找与熵相关的工具：**
```
search(query="entropy")
# 返回包含名称或描述中包含“entropy”的工具
```
#### `execute(method, params?)`
执行任意Ghidra分析工具，指定工具名称和参数。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `method` | 字符串 | 是 | 工具名称，从目录中选择（使用 `search` 查询可用工具）。 |
| `params` | 对象 | 否 | 关键字参数，作为字典传递。对于无参数要求的工具，可以省略。 |
**示例 — 列出函数：**
```
execute(method="list_functions", params={"binary_name": "test.elf", "filter": "main", "limit": 10})
```
**示例 — 反编译函数：**
```
execute(method="decompile_function", params={"binary_name": "test.elf", "name_or_addr": "main"})
```
**示例 — 模拟函数：**
```
execute(method="emulate_function", params={"binary_name": "test.elf", "name_or_addr": "decrypt", "args": [1, 2]})
```
**示例 — 列出所有二进制文件（无需参数）：**
```
execute(method="list_binaries")
```
### 错误处理
- **未知方法**：抛出 `ValueError`，并附上所有可用方法名称的列表。
- **缺少必需参数**：从底层Python方法调用中抛出 `TypeError`。
- **桥接错误**：`KeyError`（未找到二进制文件）、`RuntimeError`（反编译失败）等，直接传播并带有描述性消息。
### 何时使用代码模式
| 场景 | 推荐模式 |
|----------|-----------------|
| 使用Claude Desktop进行交互式探索 | Full |
| 自动分析流程 | Code |
| 成本敏感/高容量使用 | Code |
| 服务器首次使用 | Full |
| LLM上下文窗口较小 | Code |
| 自定义分析，超出内置工具范围 | Script |
| 探索Ghidra API进行脚本编写 | Script |
## 脚本模式
脚本模式通过实时反射和Python代码执行，提供对Ghidra Java API的直接访问。代替使用预建工具，LLM可以搜索API类、检查方法签名并执行任意Python代码，完全访问Ghidra API — 类似于可编程的Ghidra脚本环境。
### 激活
```bash
# Docker
docker compose run --rm -i ghidra-mcp --mode script
# 本地
ghidra-mcp --mode script
```
### 工具
#### `search_api(query, package?)`
使用实时Java反射，按关键字搜索Ghidra Java API类和方法。
```
search_api(query="FunctionManager")
# 返回类信息，包含所有方法签名
search_api(query="getParameters", package="ghidra.program.model.listing")
# 返回类信息，包含匹配的方法
```
#### `get_class_info(class_name)`
获取特定类的完整反射信息 — 方法、参数类型、返回类型、接口。
```
get_class_info(class_name="ghidra.program.model.listing.Function")
# 返回：{"class": "...", "methods": [{"name": "getName", "params": [], "returns": "String"}, ...]}
get_class_info(class_name="Function") # 短名称也有效
```
#### `execute_script(code, binary_name?)`
执行Python代码片段，完全访问Ghidra Java API。
```python
execute_script(
binary_name="malware.exe",
code="""
fm = program.getFunctionManager()
funcs = list(fm.getFunctions(True))
result = []
for f in funcs[:5]:
result.append({
'name': f.getName(),
'addr': str(f.getEntryPoint()),
'cc': f.getCallingConventionName(),
})
return result
"""
)
```
脚本范围内预定义变量：
- `bridge` — GhidraBridge实例
- `program` / `currentProgram` — Program对象（如果提供`binary_name`）
- `monitor` — ConsoleTaskMonitor
- 所有`ghidra.*`包可通过正常Python导入
## 配置
### 命令行标志
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--mode` | `full` | 服务器模式：`full`、`code`或`script` |
| `--transport` | `stdio` | 传输协议：`stdio`或`sse` |
| `--host` | `localhost` | SSE传输绑定主机 |
| `--port` | `8080` | SSE传输绑定端口 |
| `--project-dir` | `./ghidra-projects` | Ghidra项目目录 |
| `--project-name` | `mcp_project` | Ghidra项目名称 |
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `GHIDRA_INSTALL_DIR` | *(自动检测)* | Ghidra安装目录路径（如果PyGhidra自动检测失败，则需要） |
| `GHIDRA_ANALYSIS_TIMEOUT_SECONDS` | `300` | 每个二进制文件的分析超时时间 |
| `GHIDRA_MAX_HEAP` | `2g` | JVM最大堆大小 |
## Docker卷
| 路径 | 用途 |
|------|---------|
| `/home/ghidra/binaries` | 输入二进制文件（只读挂载） |
| `/home/ghidra/projects` | 持久化Ghidra项目数据 |
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试（使用模拟的GhidraBridge，无需Ghidra）
pytest tests/ -v
# 192个测试，涵盖完整模式、模拟、服务器、代码模式、脚本模式、CLI和验证
```
## 架构
```
MCP客户端（Claude Desktop / Claude Code / OpenCode / Continue.dev / ...）
↕ stdio或SSE（HTTP）
FastMCP服务器（server.py）
├── 完整模式：32个@mcp.tool() + 5个@mcp.resource()
├── 代码模式：search + execute → _dispatch()
└── 脚本模式：search_api + get_class_info + execute_script
↕
GhidraBridge（ghidra_bridge.py）
├── 程序缓存 （dict[str, Program]）
├── 反编译器缓存 （dict[str, DecompInterface]）
└── 模拟器缓存 （dict[str, EmulatorHelper]）
↕
PyGhidra / JPype / JVM
↕
Ghidra Java API
```
- **FastMCP** 处理MCP协议，基于stdio或SSE
- **GhidraBridge** 管理JVM生命周期、Ghidra项目、缓存的程序句柄、反编译器实例和模拟器会话
- **PyGhidra** 提供通过JPype（无需单独的Ghidra进程）进行Ghidra Java API的进程内访问
- **代码模式调度器**（`_dispatch`）将`execute(method, params)`调用转换为相应的桥接方法调用，处理参数重命名和响应包装
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器