# HackerOne MCP

An [MCP](https://modelcontextprotocol.io) server that connects Claude to the
**HackerOne Hacker API**. List your programs, pull structured scope, read and
submit reports, browse Hacktivity, and check your balance — all from inside
Claude Code.

## Tools

| Tool | What it does |
|------|--------------|
| `test_connection` | Verify credentials work (run this first) |
| `list_programs` | List programs you can access |
| `get_program` | Full details for one program by handle |
| `get_program_scope` | Structured scope (in-scope assets), filter by bounty/submission |
| `get_program_weaknesses` | Accepted weakness (CWE) types |
| `get_scope_exclusions` | Out-of-scope categories |
| `search_scope` | Search a keyword across ALL your programs' scopes |
| `list_my_reports` | Reports you've submitted |
| `get_report` | One report by ID (activities, bounties, state) |
| `submit_report` | Submit a new vulnerability report |
| `hacktivity` | Query publicly disclosed reports for intel |
| `get_balance` / `get_earnings` / `get_payouts` | Money |
| `hackerone_api` | Raw passthrough for any other endpoint |

## Setup

### 1. Get an API token
Go to <https://hackerone.com/settings/api_token/edit>, create a token, and note
both the **identifier** (username) and the **token value**.

### 2. Install deps
```bash
cd ~/projects/hackerone-mcp
uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt
```

### 3. Add credentials
```bash
cp .env.example .env
# edit .env and fill in HACKERONE_API_USERNAME + HACKERONE_API_TOKEN
```
The server auto-loads `.env` from this folder — nothing else to configure.

### 4. Test
```bash
.venv/bin/python -c "import hackerone_mcp as h; print(h.test_connection())"
```

### 5. Register with Claude Code
```bash
claude mcp add hackerone -- ~/projects/hackerone-mcp/.venv/bin/python ~/projects/hackerone-mcp/hackerone_mcp.py
```
Then in Claude: *"list my HackerOne programs"* or *"pull the scope for program X"*.

To register only for the current project instead, add `--scope project`.

## Manual config (any MCP client)
```json
{
  "mcpServers": {
    "hackerone": {
      "command": "/home/kali/projects/hackerone-mcp/.venv/bin/python",
      "args": ["/home/kali/projects/hackerone-mcp/hackerone_mcp.py"]
    }
  }
}
```
Credentials come from `.env`, or set `HACKERONE_API_USERNAME` /
`HACKERONE_API_TOKEN` in the `env` block of the config.

## Notes
- Base URL: `https://api.hackerone.com/v1`, HTTP Basic auth.
- `submit_report` creates a **real** report — review details before calling.
- `.env` is gitignored; never commit your token.