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

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:

H1_USERNAME=you H1_API_TOKEN=xxxx python -m hackerone_mcp --check-auth

On Windows 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):

{
  "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

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

python -m pip install -e ".[dev]"
python -m pytest -v