# HackerOne MCP Server

An MCP (Model Context Protocol) server that connects Claude, Codex, and other MCP clients to the HackerOne Hackers API.

## Tools Available

21 tools cover the complete documented Hacker API surface:

- Hacktivity search
- Reports: list, get, and create
- Payments: balance, earnings, and payouts
- Programs: list, get, structured scopes, scope exclusions, and weaknesses
- Report intents: list, get, create, update, delete, submit, and attachment management

---

## Setup

### 1. Install dependencies

```bash
cd hackerone-mcp
npm install
```

### 2. Get your HackerOne API credentials

1. Go to https://hackerone.com/settings/api_token/edit
2. Create a new API token
3. Note your **username** and the generated **token**

---

## Configuration

### Claude Desktop

Edit your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hackerone": {
      "command": "node",
      "args": ["/absolute/path/to/hackerone-mcp/index.js"],
      "env": {
        "HACKERONE_API_USERNAME": "your_api_token_identifier",
        "HACKERONE_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

### Claude Code (CLI)

Run once to add the MCP server to your Claude Code config:

```bash
claude mcp add hackerone \
  -e HACKERONE_API_USERNAME=your_api_token_identifier \
  -e HACKERONE_API_TOKEN=your_api_token \
  -- node /absolute/path/to/hackerone-mcp/index.js
```

Or set credentials as shell environment variables first:

```bash
export HACKERONE_API_USERNAME=your_api_token_identifier
export HACKERONE_API_TOKEN=your_api_token

claude mcp add hackerone -- node /absolute/path/to/hackerone-mcp/index.js
```

Verify it's registered:
```bash
claude mcp list
```

---

### Codex CLI

Run once to add the MCP server to Codex:

```bash
codex mcp add hackerone \
  --env HACKERONE_API_USERNAME=your_api_token_identifier \
  --env HACKERONE_API_TOKEN=your_api_token \
  -- node /absolute/path/to/hackerone-mcp/index.js
```

Or configure it directly in `config.toml`:

- **macOS/Linux:** `~/.codex/config.toml`
- **Windows:** `%USERPROFILE%\.codex\config.toml`

```toml
[mcp_servers.hackerone]
command = "node"
args = ["/absolute/path/to/hackerone-mcp/index.js"]

[mcp_servers.hackerone.env]
HACKERONE_API_USERNAME = "your_api_token_identifier"
HACKERONE_API_TOKEN = "your_api_token"
```

Verify it's registered:

```bash
codex mcp list
```

In Codex TUI, run `/mcp` to view active MCP servers.

---

### Other MCP Clients (generic stdio)

Pass the environment variables when launching:

```bash
HACKERONE_API_USERNAME=your_api_token_identifier \
HACKERONE_API_TOKEN=your_api_token \
node /path/to/hackerone-mcp/index.js
```

Or configure your client's MCP settings with:
- **command:** `node`
- **args:** `["/path/to/hackerone-mcp/index.js"]`
- **env:** `{ "HACKERONE_API_USERNAME": "...", "HACKERONE_API_TOKEN": "..." }`

---

## Example prompts

Once connected, you can ask your MCP client (Claude, Codex, etc.) things like:

- *"List my HackerOne reports"*
- *"Search Hacktivity for disclosed critical reports"*
- *"Get the full details of report 12345"*
- *"What's in scope for the nodejs program?"*
- *"Show me the policy and bounty info for the security program"*
- *"List all programs I have access to"*

---

## Security Notes

- **Never hardcode** your API token in the source files
- Always use environment variables or your client's secrets manager
- Your API token provides full access to your HackerOne account — treat it like a password

---

## Reliability settings (optional)

If you see intermittent failures (timeouts, 429 rate limits, transient 5xx), you can tune these environment variables:

- `HACKERONE_TIMEOUT_MS` (default: `20000`) — per-request timeout
- `HACKERONE_MAX_RETRIES` (default: `2`) — retries for 429/5xx and transient network errors
- `HACKERONE_API_BASE` (default: `https://api.hackerone.com/v1`) — API base URL