h1-mcp

A small, read-only Model Context Protocol server for the HackerOne Hacker API. Use it from Claude Code, Codex and opencode to pull program policy, structured scope, scope exclusions, hacktivity (dedup / prior art) and your own reports straight into the model.

Deliberately eight terse tools — every tool schema is a permanent context cost, so the surface stays small and the output is compact JSON.

Read-only by design: it only ever issues GET requests. It cannot submit or modify anything.

What you get

Why this over the stock API wrapper:

• list_programs so the agent can discover handles instead of being told them.

• check_in_scope — a real wildcard/domain/URL/IP/CIDR matcher with exclusions as caveats.

• Batched context — get_program(with_scopes=True, with_exclusions=True) in one round-trip.

• Polite client — Retry-After-aware backoff on 429/5xx, automatic pagination, typed models.

Related MCP server: HackerOne MCP Server

Requirements

• Python 3.11+

• uv (recommended) or pipx/pip

• A HackerOne account with an API token: https://hackerone.com/settings/api_token/edit

Install

1. Install the server

uv tool install git+https://github.com/gabdevele/h1-mcp

This puts an h1-mcp executable on your PATH (~/.local/bin). Make sure that directory is on PATH (it usually is).

pipx install git+https://github.com/gabdevele/h1-mcp

uvx --from git+https://github.com/gabdevele/h1-mcp h1-mcp --help

h1-mcp falls back to this form automatically when it is not installed, so the generated client configs work either way.

2. Store your credentials (once)

h1-mcp init
# HackerOne username: your-handle
# HackerOne API token: ****

This writes ~/.config/h1-mcp/env with mode 0600. Credentials live in one place, so no client config ever embeds a secret. You can also override the path with H1_MCP_ENV, or just export H1_USERNAME / H1_API_TOKEN.

3. Verify

h1-mcp doctor
# OK - authenticated. Example program visible: security

4. Register the server in your client

h1-mcp install --client all        # claude + codex + opencode
# or individually
h1-mcp install --client claude
h1-mcp install --client codex
h1-mcp install --client opencode

install uses each client's own CLI where possible, and prints a snippet when it cannot. To just see the config without writing anything:

h1-mcp config --client all

Restart the client afterwards.

Client setup (manual)

opencode

Add to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "hackerone": {
      "type": "local",
      "command": ["h1-mcp"],
      "enabled": true
    }
  }
}

Claude Code

claude mcp add hackerone -s user -- h1-mcp
claude mcp list

Or add this to .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "hackerone": { "command": "h1-mcp", "args": [] }
  }
}

Codex

codex mcp add hackerone -- h1-mcp
codex mcp list

Or in ~/.codex/config.toml:

[mcp_servers.hackerone]
command = "h1-mcp"
args = []

Any other MCP client

It is a plain stdio server: run h1-mcp (no arguments). Credentials are read from the environment or ~/.config/h1-mcp/env, so nothing else needs configuring.

Usage

Once registered, just talk to your agent. Examples:

• “List programs that offer bounties and mention their max severity in scope.”

• “Is api.acme.com in scope for the acme program? Any exclusions I should worry about?”

• “Summarize the acme policy and list the top 10 in-scope assets.”

• “Find disclosed XSS reports for acme from the last year.”

• “Show my reports that are still new.”

You can also drive it directly:

h1-mcp serve            # run the stdio server (what the clients call)
h1-mcp doctor           # check credentials + connectivity
h1-mcp --version

Configuration

Resolution order: process environment → H1_MCP_ENV file → ./.env.

Security notes

• h1-mcp init writes the credentials file as 0600.

• .env and *.env are git-ignored; never commit tokens.

• The server is read-only and only sends the token to api.hackerone.com over HTTPS.

Development

git clone https://github.com/gabdevele/h1-mcp
cd h1-mcp
uv sync --extra dev
uv run pytest
uv run ruff check src tests
uv run h1-mcp doctor

Layout:

src/h1_mcp/
  client.py    # HackerOne Hacker API client (retries, pagination, typed models)
  models.py    # pydantic response models
  scope.py     # pure in-scope matcher (wildcard/domain/URL/IP/CIDR)
  server.py    # the MCP server + 8 tools
  config.py    # credential loading/storage
  cli.py       # serve / init / doctor / install / config
tests/         # unit tests for scope, client and server (no network)

License

MIT — see LICENSE.