h1-brain: an MCP server that turns your HackerOne history into attack briefings

What h1-brain solves for bug bounty researchers

HackerOne keeps your report history, program scopes and public disclosures behind a web interface and an API. Neither is convenient when you are mid-session with an AI assistant and want it to reason about what you have already found, what a program pays for, and which assets nobody has touched. h1-brain closes that gap by moving the data into two local SQLite files and exposing it as MCP tools.

The intended user is a working bug bounty hunter who already has rewarded reports on the platform and uses Claude Desktop or Claude Code as a daily driver. The README frames the value as combining "your personal data and public knowledge" to generate attack briefings. That framing matters: the personal half of the database is empty until you sync it, so the tool's usefulness is proportional to how much you have already submitted and been paid for. A new researcher gets the public disclosure corpus and not much else.

The two-database architecture and how hack(handle) assembles a briefing

The repository ships two separate stores. `h1_data.db` holds your own synced reports, programs and scopes. `disclosed_reports.db` is committed to the repository and contains the pre-built corpus of 3,600+ publicly disclosed bounty-awarded reports. The README's diagram shows the server reading from both while writing only to your personal database, which means the public corpus is read-only from the client's perspective.

The primary tool is `hack(handle)`, and the README describes it as a fixed sequence: fetch fresh scope from the HackerOne API, pull your reports for that program from SQLite, analyze weakness patterns across all your programs, identify bounty-eligible assets with zero findings from you, cross-reference public disclosed reports for the same program, then generate a briefing with agent instructions. The output is structured into named blocks: Scope, Your Past Findings, Weakness Types That Worked, Untouched Scope, Suggested Attack Vectors, Public Disclosed Reports, and Instructions.

Two design choices stand out. First, scope is fetched live on every `hack()` call rather than read from the local cache, so a program that changed its policy an hour ago is reflected immediately. Second, the weakness-pattern analysis runs across your entire history, not just the target program, which is what lets the tool suggest vectors that paid elsewhere but have not been found here. The other tools are plain SQLite readers: `search_reports`, `get_report`, `get_report_summary`, `search_programs`, `search_scopes`, `fetch_attachment`, plus `search_disclosed_reports` and `get_disclosed_report` against the public corpus. The README notes these personal-data queries make no API calls and return instantly, and that `fetch_attachment` returns download URLs that expire in roughly an hour.

Installing h1-brain and connecting it to Claude Desktop or Claude Code

The README lists two requirements: Python 3.10 or newer and a HackerOne API token, which you generate from your HackerOne account settings. Installation is a clone plus a virtual environment.

# from the README setup section
git clone https://github.com/PatrikFehrenbach/h1-brain.git
cd h1-brain
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The dependency list is short. `requirements.txt` contains exactly `mcp` and `httpx`, so there is no heavy framework to pull in, and the public disclosure database is already in the repository as `disclosed_reports.db`.

For Claude Desktop, the README gives a JSON block to add under `mcpServers` in `claude_desktop_config.json`, with the venv Python as `command`, `server.py` as the argument, and `H1_USERNAME` plus `H1_API_TOKEN` in the `env` object. Restart the client after saving. The Claude Code path is a single CLI invocation.

claude mcp add h1-brain \
  -e H1_USERNAME=your_hackerone_username \
  -e H1_API_TOKEN=your_api_token \
  -- /path/to/h1-brain/venv/bin/python /path/to/h1-brain/server.py

After connecting, the README's first-run steps are two tool calls: `fetch_rewarded_reports` to pull your bounty-awarded reports with full write-ups, and `fetch_programs` to pull the programs you can access. The README calls the first one the most important step and says both only need to be run once, with periodic re-runs to sync new reports. A reasonable first real use is then to call `hack(handle)` on a program you already know well, so you can judge the briefing against your own memory of the target before relying on it for a program you have never touched.

Where h1-brain is the wrong tool

The README is explicit that `hack(handle)` "puts the AI in offensive mode" and returns instructions rather than findings. Nothing in the repository scans, fuzzes or sends a request to a target. There is no recon engine, no payload library and no crawl step. If you want a tool that probes an asset and reports back, h1-brain is not it, and the naming may mislead people into expecting otherwise.

The second limitation is data freshness on the public side. `disclosed_reports.db` is checked into the repository, and the README does not document a refresh command, a scheduled job or a versioning scheme for it. The 3,600+ figure is a snapshot of whatever was public when that file was committed. The README also does not document rollback if a sync writes something you did not want, so treat `h1_data.db` as a file worth backing up before re-running the fetch tools.

Third, the tool is only as good as your own submission history. The weakness-pattern analysis and the untouched-asset detection both depend on your reports being present and correctly attributed. If your HackerOne account has few or no rewarded reports, the briefing degenerates into public disclosure data plus scope, which you could assemble yourself. Finally, the setup requires placing a HackerOne API token in a plaintext config file, and the README says nothing about token scoping or rotation.

How h1-brain differs from a general MCP filesystem or search server

The obvious alternative is a generic MCP server that gives an assistant access to local files or a web search, and pointing it at exported HackerOne data. The difference is in the query surface. A filesystem server gives the model raw files and leaves the joins to the model's context window; h1-brain pre-computes the joins that matter here, specifically the intersection of fresh scope, your past findings on that program, and weaknesses rewarded on other programs but absent from this one.

That intersection is the actual product. Rebuilding it by hand means exporting reports, parsing scope JSON, and diffing weakness types across programs, which is exactly the work the tool exists to remove. The cost of that convenience is a fixed schema: the tools return what the README's tables describe, and there is no documented way to extend the briefing with your own notes or a custom data source. A generic server is more flexible and more work; h1-brain is narrower and faster to a first useful answer.

Licence and the maintenance picture

h1-brain is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive enough that wrapping it in an internal workflow carries few obligations, but the licence text in the repository is the authoritative version and nothing here is legal advice.

The repository is not archived, and the last push was on 2026-04-07. That is roughly five months before the date of this article, so the project is not abandoned, but it is also not receiving continuous changes. Upgrade cost is low by construction: two dependencies, no pinned versions in `requirements.txt`, and a single `server.py` entry point. The upgrade risk sits in the data files rather than the code. If `disclosed_reports.db` is replaced upstream, your local copy will not update on its own, and the README does not describe a migration path for `h1_data.db` if the schema changes between versions.

Editorial conclusion

Adopt h1-brain if you already have a body of rewarded HackerOne reports and want an MCP client to reason over them alongside public disclosure data; the payoff scales with your own history, so a researcher with a handful of reports gets little from the personal database. Skip it if you want an automated scanner or a tool that finds bugs without you driving it, and skip it if you cannot store a HackerOne API token in a local config file. Before trusting the briefings, verify three things yourself: that fetch_rewarded_reports and fetch_programs actually populated h1_data.db, that the scopes returned by hack() match what the program page shows today, and that the disclosed_reports.db shipped in the repository is the version you expect, since the README does not document how or when that file is refreshed.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PatrikFehrenbach/h1-brain on GitHub
4. README