内容
# Ghidra MCP
[简体中文](README.zh-CN.md)
一个用于无头逆向工程的单进程MCP服务器。一个Python进程通过PyGhidra启动JVM，管理持久化的Ghidra项目，并向AI客户端公开35种面向任务的工具。
> 安全基准是Ghidra 12.1.2或更高版本。Streamable HTTP需要Bearer令牌，部署到本地主机以外时必须在受信任的反向代理处终止TLS。
## 项目状态
项目源代码遵循Apache License 2.0许可。Ghidra、PyGhidra、MCP SDK和其他第三方组件仍遵循其各自的许可。
此服务旨在进行受控的无头分析，而不是作为多租户沙盒。Ghidra解析不受信任的二进制文件，HTTP令牌持有者可以调用分析和变异工具。请使用隔离的容器、只读输入挂载、专用的持久化卷和最小的网络访问。
## 容器镜像
仓库中包含一个GitHub Actions工作流，每次推送到`main`分支后，使用`--no-cache`构建`linux/amd64`镜像，并将版本化和`latest`标签发布到GHCR，拉取已发布的摘要，并验证`/health`端点是否与源版本和提交一致。
一旦GHCR软件包发布并且其可见性设置为公开，您就可以在无需身份验证的情况下拉取它：
```bash
docker pull ghcr.io/xjoker/ghidra-mcp:latest
```
GHCR默认创建新的容器软件包为私有。仅凭成功的工作流无法证明匿名可用性；请通过未经身份验证的拉取操作进行验证。
使用持久化项目和只读输入目录运行镜像：
```bash
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
)
```
隐藏的提示会将令牌值从shell历史记录中排除。任何具有Docker守护进程访问权限的人仍可以检查容器环境变量；请相应地限制守护进程访问权限。
通过`http://127.0.0.1:8765/mcp`与`Authorization: Bearer <token>`连接。公共健康检查端点是`http://127.0.0.1:8765/health`。
要从源代码构建，请将`<VERSION>`替换为根目录`VERSION`文件中的值：
```bash
docker buildx build \
--platform linux/amd64 \
--no-cache \
--load \
--build-arg GIT_COMMIT=<full Git commit> \
--build-arg VERSION=<VERSION> \
-t ghidra-mcp:<VERSION> .
```
## 本地_stdio
要求：Python 3.11+，Ghidra 12.1.2+，`uv`和可写入的项目目录。
```bash
uv sync --locked
cp .env.example .env
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra \
GHIDRA_MCP_TRANSPORT=stdio \
uv run ghidra-mcp
```
MCP客户端应自行启动_stdio进程。等效的通用配置如下：
```json
{
"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输入边界；符号链接无法逃脱它 |
| `GHIDRA_MCP_AUTH_TOKEN` | 无 | 必须的HTTP令牌，至少32个UTF-8字节 |
公共URL不能包含通配符主机、用户数据、查询字符串或路径前缀。机密仅接受来自环境变量或未跟踪的`.env`；请勿在TOML、日志、shell历史记录或Git中放置实际令牌。
## 文档
[GitHub Wiki](https://github.com/xjoker/ghidra-mcp/wiki)包含详细的中文快速入门指南、工具目录和操作手册。
- [快速入门](https://github.com/xjoker/ghidra-mcp/wiki/快速入门)
- [工具目录](https://github.com/xjoker/ghidra-mcp/wiki/工具目录)
- [操作](https://github.com/xjoker/ghidra-mcp/wiki/操作)
- [贡献](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
## 开发
该项目目前支持源代码安装和本地构建；未声明PyPI分发。
```bash
uv sync --locked --extra dev
uv run --locked pytest -m 'not integration' -q
uv run --locked ruff check src tests scripts
```
有关fixture生成和实际Ghidra集成测试，请参见[CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
项目源代码遵循[Apache License 2.0](LICENSE)。属性记录在[NOTICE](NOTICE)中。第三方组件仍遵循其各自的许可证。
