Content
# hackerone-mcp
A local, **read-only** MCP server that connects your HackerOne researcher account
to Claude Desktop and Claude Code. It helps you find the best targets, analyze
program scopes, review your reports/earnings, and draft bug reports (which you
submit yourself — the server never writes to your account).
## How it works
Claude Desktop or Claude Code spawns this server as a local subprocess and talks
to it over stdio using the Model Context Protocol. Every tool is read-only. The
server reaches HackerOne over **two separate paths**: your private account data
through the **authenticated official API**, and public disclosed-report data
through an **unauthenticated public endpoint** (so your account is never involved
in those requests).
```
┌──────────────────┐ ┌──────────────────┐
│ Claude Desktop │ │ Claude Code │
└────────┬─────────┘ └────────┬─────────┘
└───────────┬───────────────┘
│ MCP over stdio
│ (launches: python -m hackerone_mcp)
▼
┌───────────────────────────────────────────────────────────────────── ┐
│ hackerone-mcp (local server) │
│ │
│ server.py ── FastMCP tools │
│ │ programs · scopes · count/filter · rank · weaknesses │
│ │ my_reports · earnings · draft_report · raw_get │
│ │ search_disclosed_reports · list_cwe_types · directory │
│ │ │
│ ├── config.py ◄──────── .env (H1_ENV_FILE: H1_USERNAME / TOKEN) │
│ │ │
│ └── tools.py ── orchestrates each request │
│ │ │
│ ├── cache.py ......... disk cache (1h TTL) — hit? return │
│ │ │
│ ├── analysis.py ...... rank / filter / summarize ┐ │
│ ├── hacktivity.py .... build query / project │ pure │
│ │ (no I/O) ┘ funcs │
│ │ │
│ ├── client.py ........ httpx + HTTP Basic auth ─────────┐ │
│ │ (GET only, 429 retry) │ │
│ └── graphql_client.py httpx POST, NO auth ──────────┐ │ │
│ (read queries only) │ │ │
└────────────────────────────────────────────────────────────-----│--│--┘
│ │
authenticated, read-only GET (HTTPS) ────────┼──┘
your account data │
▼
┌──────────────────────────────┐
│ api.hackerone.com/v1 │
│ /hackers/programs … │
└──────────────────────────────┘
unauthenticated, read-only POST (HTTPS)
public disclosed reports │
▼
┌──────────────────────────────┐
│ hackerone.com/graphql │
│ (public hacktivity) │
└──────────────────────────────┘
```
**Two flows, one pattern:** Claude calls a tool → `tools.py` checks `cache.py` →
on a miss it hits the right backend → a pure function (`analysis.py` /
`hacktivity.py`) shapes the result → it goes back up to Claude.
- **Account path** (your programs, scopes, reports, earnings): `client.py` makes
an authenticated read-only **GET** to `api.hackerone.com/v1`. Your token never
leaves your machine except as the Basic-auth header.
- **Public path** (disclosed-report / CWE / directory search): `graphql_client.py`
makes an **unauthenticated** read-only **POST** to `hackerone.com/graphql` — no
token or cookie is ever attached, so these requests carry no account risk.
## Requirements
- Python 3.10+ (tested on 3.13)
- A HackerOne API token: hackerone.com → Settings → **API Token**. Use the
narrowest read scope available.
## Install
```bash
git clone <this repo> hackerone-mcp
cd hackerone-mcp
python -m pip install -e .
```
## Configure credentials
Set two environment variables (these go in your MCP client config below):
- `H1_USERNAME` — your HackerOne username
- `H1_API_TOKEN` — the API token you generated
Optional: `H1_CACHE_DIR`, `H1_CACHE_TTL` (seconds, default 3600).
Verify your token works:
```bash
H1_USERNAME=you H1_API_TOKEN=xxxx python -m hackerone_mcp --check-auth
```
On Windows PowerShell:
```powershell
$env:H1_USERNAME="you"; $env:H1_API_TOKEN="xxxx"; python -m hackerone_mcp --check-auth
```
Expected: `OK: authenticated as you. N program(s) accessible.`
## Connect to Claude Desktop
Edit `claude_desktop_config.json`
(Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
"mcpServers": {
"hackerone": {
"command": "python",
"args": ["-m", "hackerone_mcp"],
"env": {
"H1_USERNAME": "your_username",
"H1_API_TOKEN": "your_api_token"
}
}
}
}
```
Restart Claude Desktop.
## Connect to Claude Code
```bash
claude mcp add hackerone --env H1_USERNAME=your_username --env H1_API_TOKEN=your_api_token -- python -m hackerone_mcp
```
Or add an `.mcp.json` entry with the same `command`/`args`/`env`.
## Tools
- `list_programs` — programs your account can access (`compact=true` for a small
handle/name/bounty/state listing; the full list is several MB)
- `count_programs` — totals only: program count, bounty programs, VDPs, and a
submission-state breakdown (use this for "how many ..." questions)
- `get_program` — full policy/details for a handle
- `get_program_scopes` — structured scopes, summarized in/out of scope
- `get_program_weaknesses` — the CWE/weakness types a program tracks
- `filter_programs` — compact list filtered by offers_bounties / submission_state / bookmarked (e.g. all VDPs)
- `list_my_reports` — your own submitted reports (compact; use `get_report` for full detail)
- `search_scopes` — search assets across your programs (`limit` for a quick scan)
- `rank_programs` — rank programs for hunting (bounties, scope, severity; `limit` for a quick scan)
- `get_balance`, `list_earnings` — your payments
- `get_report` — read a report by id
- `draft_report` — format a report in markdown (you submit it yourself)
- `raw_get` — authenticated read-only GET against any v1 API path
- `search_disclosed_reports` — search PUBLIC disclosed reports by keyword / severity / CWE / CVE / program; `sort` ("relevance"/"recent", default relevance for keyword searches) and `since`/`until` (YYYY-MM-DD) date bounds
- `list_cwe_types` — valid CWE names for the `cwe` filter
- `search_directory` — search the public program directory by name
> **Note:** `search_scopes` and `rank_programs` scan every program you can access
> (one API call per program on a cold cache — potentially hundreds). Results are
> cached for an hour, so the first call is slow and later calls are fast. Pass
> `limit` (e.g. 50) for a quick partial scan, or `refresh=true` to bypass the cache.
## Security
Your API token is stored in plaintext in the client config file. Protect that
file (restrict permissions), use a narrow-scope token, and revoke/rotate it from
HackerOne if it is ever exposed. This server makes **only read-only requests**
(authenticated GETs to the official API, plus unauthenticated read-only GraphQL
POSTs to the public hacktivity endpoint) — it cannot submit, edit, or delete
anything on your account.
## Public hacktivity search (Part 2)
`search_disclosed_reports`, `list_cwe_types`, and `search_directory` read
HackerOne's **public** disclosed-report data through its undocumented GraphQL
endpoint, **unauthenticated** — no token or cookie is sent, so these calls carry
no risk to your account. They are read-only (the server never sends mutations).
Because the endpoint is undocumented, the baked-in queries can break if HackerOne
changes its schema. The exact queries were captured on 2026-06-28 and saved to
`docs/superpowers/reference/hackerone-graphql-captures-2026-06-28.json`; re-capture
from a browser and update `graphql_client.py` if a hacktivity tool stops working.
## Development
```bash
python -m pip install -e ".[dev]"
python -m pytest -v
```
