内容
# hackerone-mcp
一个本地的 **只读** MCP 服务器，用于连接您的 HackerOne 研究人员账户
到 Claude Desktop 和 Claude Code。它帮助您找到最佳目标，分析
程序范围，查看您的报告/收益，并草拟漏洞报告（您自己提交 —
服务器从不写入您的账户）。
## 工作原理
Claude Desktop 或 Claude Code 将此服务器作为本地子进程启动，并通过 stdio 使用模型上下文协议与其通信。所有工具都是只读的。服务器通过 **两条独立路径** 访问 HackerOne：您的私有账户数据
通过 **身份验证的官方 API**，以及公共披露报告数据
通过 **未经身份验证的公共端点** （因此您的账户从未涉及
这些请求）。
```
┌──────────────────┐ ┌──────────────────┐
│ Claude Desktop │ │ Claude Code │
└────────┬─────────┘ └────────┬─────────┘
└───────────┬───────────────┘
│ MCP over stdio
│ （启动：python -m hackerone_mcp）
▼
┌───────────────────────────────────────────────────────────────────── ┐
│ hackerone-mcp （本地服务器） │
│ │
│ server.py ── FastMCP 工具 │
│ │ 程序 · 范围 · 计数/筛选 · 排名 · 弱点 │
│ │ 我的报告 · 收益 · 草拟报告 · 原始获取 │
│ │ 搜索公开报告 · 列出 CWE 类型 · 目录 │
│ │ │
│ ├── config.py ◄──────── .env （H1_ENV_FILE: H1_USERNAME / TOKEN） │
│ │ │
│ └── tools.py ── 协调每个请求 │
│ │ │
│ ├── cache.py ......... 磁盘缓存（1小时 TTL）— 命中？返回 │
│ │ │
│ ├── analysis.py ...... 排名 / 筛选 / 总结 ┐ │
│ ├── hacktivity.py .... 构建查询 / 项目 │ 纯函数 │
│ │ （无 I/O） └─ 函数 │
│ │ │
│ ├── client.py ........ httpx + HTTP 基本身份验证 ─────────┐ │
│ │ （仅 GET，429 重试） │ │
│ └── graphql_client.py httpx POST，无身份验证 ──────────┐ │ │
│ （仅读取查询） │ │ │
└────────────────────────────────────────────────────────────-----│--│--┘
│ │
身份验证， 只读 GET（HTTPS） ────────┼──┘
您的账户数据 │
▼
┌──────────────────────────────┐
│ api.hackerone.com/v1 │
│ /hackers/programs … │
└──────────────────────────────┘
无身份验证， 只读 POST（HTTPS）
公共披露报告 │
▼
┌──────────────────────────────┐
│ hackerone.com/graphql │
│ （公共 hacktivity） │
└──────────────────────────────┘
```
**两种流程，一种模式：** Claude 调用工具 → `tools.py` 检查 `cache.py` →
未命中时访问正确的后端 → 纯函数（`analysis.py` /
`hacktivity.py`） 塑造结果 → 返回到 Claude。
- **账户路径** （您的程序，范围，报告，收益）：`client.py` 进行
身份验证的只读 **GET** 到 `api.hackerone.com/v1`。您的令牌从未
离开您的机器，除了作为基本身份验证标头。
- **公共路径** （公开报告 / CWE / 目录搜索）：`graphql_client.py`
进行 **无身份验证** 只读 **POST** 到 `hackerone.com/graphql` — 无
令牌或 cookie 附加，因此这些请求不承担账户风险。
## 要求
- Python 3.10+（测试于 3.13）
- 一个 HackerOne API 令牌：hackerone.com → 设置 → **API 令牌**。使用
可用的最窄读取范围。
## 安装
```bash
git clone <此仓库> hackerone-mcp
cd hackerone-mcp
python -m pip install -e .
```
## 配置凭证
设置两个环境变量（这些放在您的 MCP 客户端配置中）：
- `H1_USERNAME` — 您的 HackerOne 用户名
- `H1_API_TOKEN` — 您生成的 API 令牌
可选：`H1_CACHE_DIR`，`H1_CACHE_TTL`（秒，默认 3600）。
验证您的令牌是否有效：
```bash
H1_USERNAME=您 H1_API_TOKEN=xxxx python -m hackerone_mcp --check-auth
```
在 Windows PowerShell 上：
```powershell
$env:H1_USERNAME="您"; $env:H1_API_TOKEN="xxxx"; python -m hackerone_mcp --check-auth
```
预期输出：`OK: authenticated as 您. N 程序（s）可访问。`
## 连接到 Claude Desktop
编辑 `claude_desktop_config.json`
（Windows：`%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"hackerone": {
"command": "python",
"args": ["-m", "hackerone_mcp"],
"env": {
"H1_USERNAME": "您的用户名",
"H1_API_TOKEN": "您的 API 令牌"
}
}
}
}
```
重启 Claude Desktop。
## 连接到 Claude Code
```bash
claude mcp add hackerone --env H1_USERNAME=您的用户名 --env H1_API_TOKEN=您的 API 令牌 -- python -m hackerone_mcp
```
或添加具有相同 `command`/`args`/`env` 的 `.mcp.json` 条目。
## 工具
- `list_programs` — 您的账户可以访问的程序（`compact=true` 表示小型
处理/名称/赏金/状态列表；完整列表有几 MB）
- `count_programs` — 仅总数：程序计数，赏金程序，VDP 和
提交状态分解（用于“多少...”问题）
- `get_program` — 句柄的完整策略/详细信息
- `get_program_scopes` — 结构化范围，总结范围内/范围外
- `get_program_weaknesses` — 程序跟踪的 CWE/弱点类型
- `filter_programs` — 按 offers_bounties / submission_state / bookmarked 筛选的紧凑列表（例如，所有 VDP）
- `list_my_reports` — 您自己的提交报告（紧凑；使用 `get_report` 获取完整详细信息）
- `search_scopes` — 在您的程序中搜索资产（`limit` 表示快速扫描）
- `rank_programs` — 对程序进行狩猎排名（赏金，范围，严重性；`limit` 表示快速扫描）
- `get_balance`，`list_earnings` — 您的付款
- `get_report` — 按 ID 读取报告
- `draft_report` — 以 markdown 格式报告（您自己提交）
- `raw_get` — 对任何 v1 API 路径进行身份验证的只读 GET
- `search_disclosed_reports` — 按关键词/严重性/CWE/CVE/程序搜索 **公共** 公开报告；`sort`（“相关性”/“最近”，默认相关性搜索关键词）和 `since`/`until`（YYYY-MM-DD）日期范围
- `list_cwe_types` — 用于 `cwe` 筛选的有效 CWE 名称
- `search_directory` — 按名称搜索公共程序目录
> **注意：** `search_scopes` 和 `rank_programs` 扫描您可以访问的每个程序
> （一个 API 调用每个程序在冷缓存上 — 可能有数百个）。结果缓存一小时，
> 因此第一个调用很慢，后续调用很快。传递 `limit`（例如 50）进行快速部分扫描，
> 或 `refresh=true` 绕过缓存。
## 安全
您的 API 令牌以纯文本形式存储在客户端配置文件中。保护该
文件（限制权限），使用窄范围令牌，并在
HackerOne 上将其暴露时撤销/轮换它。此服务器仅发出 **只读请求**
（身份验证的 GET 请求到官方 API，以及对公共 hacktivity 端点的无身份验证只读 GraphQL
POST 请求）— 它不能提交，编辑或删除
您的账户上的任何内容。
## 公共 hacktivity 搜索（第 2 部分）
`search_disclosed_reports`，`list_cwe_types` 和 `search_directory` 读取
HackerOne 的 **公共** 公开报告数据，通过其未记录的 GraphQL
端点，**无身份验证** — 不发送令牌或 cookie，因此这些调用不承担
账户风险。它们是只读的（服务器从不发送突变）。
由于端点未记录，因此内置查询可能会因 HackerOne
更改其架构而中断。确切的查询于 2026-06-28 捕获并保存到
`docs/superpowers/reference/hackerone-graphql-captures-2026-06-28.json`；如果 hacktivity 工具停止工作，请从浏览器重新捕获并更新 `graphql_client.py`。
## 开发
```bash
python -m pip install -e ".[dev]"
python -m pytest -v
```
