xjoker/ghidra-mcp
GitHub: xjoker/ghidra-mcp
该项目为无头二进制逆向工程提供了一个单进程 MCP 服务器，通过 PyGhidra 驱动 Ghidra 并向 AI 客户端开放 35 个任务导向的分析工具，实现自动化的二进制逆向分析流程。
Stars: 1 | Forks: 0
# Ghidra MCP
[简体中文](README.zh-CN.md)
一个用于无头逆向工程的单进程 MCP server。一个 Python 进程通过 PyGhidra 启动 JVM，管理持久化的 Ghidra 项目，并向 AI 客户端暴露 35 个面向任务的工具。
## 项目状态
项目源代码基于 Apache License 2.0 授权。Ghidra、PyGhidra、MCP SDK 及其他第三方组件仍保留其各自的许可证。
本服务旨在用于受控的无头分析，而非作为多租户沙盒。Ghidra 会解析不受信任的二进制文件，且 HTTP token 持有者可以调用分析和修改工具。请使用隔离的容器、只读的输入挂载、专用的持久化存储卷以及最小的网络访问权限。
## 容器镜像
该仓库包含一个 GitHub Actions 工作流，在每次推送到 `main` 分支后，它会使用 `--no-cache` 构建 `linux/amd64` 镜像，将带有版本号和 `latest` 标签的镜像发布到 GHCR，拉取已发布的摘要，并根据源代码版本和提交验证 `/health`。
一旦 GHCR 包发布并将其可见性设置为公开，即可在无需身份验证的情况下拉取它：
```
docker pull ghcr.io/xjoker/ghidra-mcp:latest
```
GHCR 默认将新建的容器包设为私有。仅工作流成功运行并不能证明其可以匿名访问；请通过未经验证拉取来进行确认。
运行镜像时，请使用持久化项目和只读输入目录：
```
docker volume create ghidra-mcp-projects
(
read -rsp 'Ghidra MCP token: ' GHIDRA_MCP_AUTH_TOKEN && echo
export GHIDRA_MCP_AUTH_TOKEN
docker run -d --name ghidra-mcp \
--platform linux/amd64 \
-p 127.0.0.1:8765:8765 \
-e GHIDRA_MCP_PUBLIC_URL=http://127.0.0.1:8765 \
-e GHIDRA_MCP_AUTH_TOKEN \
-v ghidra-mcp-projects:/data/projects \
-v /absolute/path/to/binaries:/data/input:ro \
ghcr.io/xjoker/ghidra-mcp:latest
)
```
隐藏的提示让 token 值不会留在 shell 历史记录中。但任何拥有 Docker daemon 访问权限的人仍然可以检查容器环境变量；请相应地限制 daemon 访问权限。
使用 `Authorization: Bearer ` 连接到 `http://127.0.0.1:8765/mcp`。公开的健康检查端点为 `http://127.0.0.1:8765/health`。
要从源代码构建，请将 `` 替换为根目录下 `VERSION` 文件中的值：
```
docker buildx build \
--platform linux/amd64 \
--no-cache \
--load \
--build-arg GIT_COMMIT= \
--build-arg VERSION= \
-t ghidra-mcp: .
```
## 本地 stdio
要求：Python 3.11+、Ghidra 12.1.2+、`uv` 以及一个可写的项目目录。
```
uv sync --locked
cp .env.example .env
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra \
GHIDRA_MCP_TRANSPORT=stdio \
uv run ghidra-mcp
```
MCP 客户端应自行启动 stdio 进程。等效的通用配置如下：
```
{
"mcpServers": {
"ghidra": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ghidra-mcp",
"run",
"ghidra-mcp"
],
"env": {
"GHIDRA_INSTALL_DIR": "/absolute/path/to/ghidra",
"GHIDRA_MCP_TRANSPORT": "stdio"
}
}
}
}
```
字段名称和配置位置因客户端而异。对于 Streamable HTTP，请配置 `/mcp` URL 和 Bearer 授权请求头。本项目不提供 Ghidra GUI 自动化功能。
## 配置
优先级顺序为：环境变量 > `.env` > TOML > 默认值。默认的 TOML 文件是 `data/config/default.toml`。
| 变量 | 默认值 | 用途 |
|---|---:|---|
| `GHIDRA_INSTALL_DIR` | 无 | 必需的 Ghidra 安装目录 |
| `GHIDRA_MCP_ANALYSIS_TIMEOUT_SECONDS` | `300` | 自动分析超时时间，从 1 到 3600 秒 |
| `GHIDRA_MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
| `GHIDRA_MCP_HOST` | `127.0.0.1` | HTTP 监听地址 |
| `GHIDRA_MCP_PORT` | `8765` | HTTP 端口，从 1 到 65535 |
| `GHIDRA_MCP_PUBLIC_URL` | 无 | 在 HTTP 模式下客户端看到的必需 HTTP(S) 根 URL |
| `GHIDRA_MCP_STORAGE_ROOT` | `data/projects` | 持久化 Ghidra 项目目录 |
| `GHIDRA_MCP_INPUT_ROOT` | 无 | 必需的 HTTP 输入边界；symlink 无法逃逸此目录 |
| `GHIDRA_MCP_AUTH_TOKEN` | 无 | 必需的 HTTP token，至少 32 个 UTF-8 字节 |
公开 URL 不能包含通配符主机、用户信息、查询字符串或路径前缀。密钥只能从环境变量或未跟踪的 `.env` 文件中获取；请勿将真实的 token 放入 TOML、日志、shell 历史记录或 Git 中。
## 文档
[GitHub Wiki](https://github.com/xjoker/ghidra-mcp/wiki) 包含了详细的英文入门指南、工具目录和运维手册。
- [入门指南](https://github.com/xjoker/ghidra-mcp/wiki/Getting-started)
- [工具目录](https://github.com/xjoker/ghidra-mcp/wiki/Tool-catalog)
- [运维手册](https://github.com/xjoker/ghidra-mcp/wiki/Operations)
- [贡献指南](CONTRIBUTING.md)
- [安全政策](SECURITY.md)
## 开发
该项目目前支持源码安装和本地构建；未声明任何 PyPI 发行版。
```
uv sync --locked --extra dev
uv run --locked pytest -m 'not integration' -q
uv run --locked ruff check src tests scripts
```
## 许可证
项目源代码基于 [Apache License 2.0](LICENSE) 提供。归属信息记录在 [NOTICE](NOTICE) 中。第三方组件保留其各自的许可证。
标签：安全规则引擎, 请求拦截, 逆向工具