🛡️ hackerone-mcp

A Model Context Protocol server for the HackerOne Hacker API

Drive your bug-bounty workflow — reports, programs, scope, hacktivity, payouts and AI-assisted drafts — straight from any MCP-capable client like Claude Code.

✨ Highlights

• 21 tools covering the entire documented Hackers surface of the HackerOne API.
• Pure ESM, zero build step — just node src/index.js. Uses the runtime's global fetch/FormData (Node ≥ 18).
• Read-safe by design — only the documented Hackers endpoints are implemented; no Customer/admin surface.
• Resilient client — automatic JSON:API pagination plus 429 back-off honoring Retry-After.
• Minimal deps — only @modelcontextprotocol/sdk and zod.

📋 Prerequisites

| Requirement | Notes | |---|---| | Node.js ≥ 18 | Needs global fetch / FormData / Blob | | HackerOne API token | HackerOne → Settings → API Token |

Authentication is HTTP Basic using your token identifier as the username and the token value as the password, supplied through environment variables.

🔌 Register in Claude Code

Add one of the blocks below to your ~/.claude.json under mcpServers, then restart Claude Code (or reconnect the server).

Option A — via npx (recommended, no clone)

"hackerone": {
  "command": "npx",
  "args": ["-y", "hackerone-mcp"],
  "env": {
    "H1_USERNAME": "YOUR-USERNAME",
    "H1_API_TOKEN": "YOUR-TOKEN"
  },
  "type": "stdio"
}

Option B — from a local clone

git clone https://github.com/j0hndo/hackerone-mcp.git
cd hackerone-mcp
npm install

"hackerone": {
  "command": "node",
  "args": [
    "/ABSOLUTE/PATH/TO/hackerone-mcp/src/index.js"
  ],
  "env": {
    "H1_USERNAME": "YOUR-USERNAME",
    "H1_API_TOKEN": "YOUR-TOKEN"
  },
  "type": "stdio"
}

| Field | Value | |---|---| | args (Option B) | Absolute path to src/index.js in this folder. On Windows use forward slashes, e.g. C:/Users/you/hackerone-mcp/src/index.js | | H1_USERNAME | Your HackerOne API token identifier | | H1_API_TOKEN | Your HackerOne API token value |

Works with any MCP client over stdio, not just Claude Code — point your client at npx -y hackerone-mcp (or node src/index.js) with the two env vars set.

🔥 Smoke test (read-only)

Verify your token and connectivity without writing anything:

# PowerShell
$env:H1_USERNAME="<id>"; $env:H1_API_TOKEN="<token>"; node scripts/smoke.js

# bash / zsh
H1_USERNAME=<id> H1_API_TOKEN=<token> node scripts/smoke.js

🧰 Tools

| Tool | Endpoint | |---|---| | list_my_reports | GET /hackers/me/reports | | get_report | GET /hackers/reports/{id} | | submit_report | POST /hackers/reports |

| Tool | Endpoint | |---|---| | search_hacktivity | GET /hackers/hacktivity | | list_programs | GET /hackers/programs | | get_program | GET /hackers/programs/{handle} | | get_program_scope | GET /hackers/programs/{handle}/structured_scopes | | get_program_weaknesses | GET /hackers/programs/{handle}/weaknesses | | get_program_scope_exclusions | GET /hackers/programs/{handle}/scope_exclusions |

| Tool | Endpoint | |---|---| | get_balance | GET /hackers/payments/balance | | get_earnings | GET /hackers/payments/earnings | | get_payouts | GET /hackers/payments/payouts |

| Tool | Endpoint | |---|---| | list_report_intents | GET /hackers/report_intents | | create_report_intent | POST /hackers/report_intents | | get_report_intent | GET /hackers/report_intents/{id} | | update_report_intent | PATCH /hackers/report_intents/{id} | | delete_report_intent | DELETE /hackers/report_intents/{id} | | submit_report_intent | POST /hackers/report_intents/{id}/submit | | list_report_intent_attachments | GET /hackers/report_intents/{id}/attachments | | upload_report_intent_attachment | POST /hackers/report_intents/{id}/attachments | | delete_report_intent_attachment | DELETE /hackers/report_intents/{id}/attachments/{id} |

⏱️ Rate limits

The HackerOne Hacker API allows 600 reads/min and 25 writes / 20 s. This client automatically retries 429 responses using the Retry-After header.

📦 Project layout

hackerone-mcp/
├── src/
│   ├── index.js      # MCP server — tool definitions (zod schemas)
│   └── h1client.js   # HackerOne Hacker API client (fetch, pagination, back-off)
├── scripts/
│   └── smoke.js      # read-only connectivity check
├── package.json
└── README.md

🧭 Scope & limitations

This server implements only the documented Hackers section of the HackerOne API. No Customer/program-owner endpoints are included.

Not currently implemented (undocumented in the Hacker section):

• GET /hackers/me (profile)
• POST /hackers/reports/{id}/activities (comments)

PRs welcome if HackerOne documents these.

🤝 Contributing

Issues and pull requests are welcome. Keep the server faithful to the documented Hacker API surface and preserve the read-safe boundary.

⚖️ License

MIT © j0hndo