HEARTH

HEARTH MCP server

Ask your AI assistant what to hunt for. This MCP server gives Claude, Cursor, VS Code and other MCP clients read-only access to HEARTH, the community library of threat hunting hypotheses.

Questions you can ask:

• "What can I hunt for Volt Typhoon with firewall and appliance logs?"
• "Find hunts for macOS persistence."
• "We only have Windows endpoint and identity logs. Which hunts can we run fully?"
• "Show me H432."

Tools

Every tool is read-only. Retired hunts are hidden unless you ask for them.

Install

You need Node.js 20 or later. Each snippet runs the published package with npx.

Claude Code

claude mcp add hearth -- npx -y @thorcollective/hearth-mcp

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{  "mcpServers": {    "hearth": {      "command": "npx",      "args": ["-y", "@thorcollective/hearth-mcp"]    }  }}

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{  "mcpServers": {    "hearth": {      "command": "npx",      "args": ["-y", "@thorcollective/hearth-mcp"]    }  }}

VS Code

Add this to .vscode/mcp.json in your workspace:

{  "servers": {    "hearth": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@thorcollective/hearth-mcp"]    }  }}

Settings

Set them in your client's config, for example "env": { "HEARTH_OFFLINE": "1" } next to "args".

Locked-down setup (enterprise)

For teams that review every change before it reaches analysts:

• Pin the version. npx -y @thorcollective/hearth-mcp always fetches the latest release. Name an exact version instead, and nothing changes until you choose to upgrade.
• Turn off the network. HEARTH_OFFLINE=1 stops the daily check, so the server only uses the hunt data that shipped with the version you pinned.
• Or use your own mirror. Set HEARTH_DATA_URL to an internal copy of the site's data files, which you update on your own schedule.
• Verify the package. After installing, run npm audit signatures to check that the package was built from this repository by GitHub Actions.

For example, in Claude Desktop:

{  "mcpServers": {    "hearth": {      "command": "npx",      "args": ["-y", "@thorcollective/[email protected]"],      "env": { "HEARTH_OFFLINE": "1" }    }  }}

Releases lists every version.

Other clients

Any MCP client that supports stdio servers can run the same command: npx -y @thorcollective/hearth-mcp.

Privacy and security

• No telemetry. The server sends nothing anywhere.
• One small network check a day. At most once every 24 hours the server asks hearth.thorcollective.com whether the hunt data has changed. It uses conditional requests, so usually nothing is downloaded. It sends only those requests and a hearth-mcp/<version> user agent.
• Works offline. If the site can't be reached, or sends data that fails validation, the server keeps using its last good copy, falling back to the snapshot bundled with each release.
• Hunt text is treated as untrusted. Hunts are written by the community:
  • The server makes hidden and right-to-left characters visible, and removes hidden text.
  • It caps field lengths.
  • It labels every hunt text field as untrusted, so your assistant reads it as data, not instructions.
  • New hunts are also checked for prompt-injection text in CI before they merge.
• Review detection queries before you run them, as you would any query from the internet.
• Verify the package: releases are published from GitHub Actions with npm provenance. Run npm audit signatures after installing to check it.

Develop

From the repository root:

npm ci && npm ci --prefix mcpnpm run build --prefix mcp      # bundle to mcp/dist and snapshot site data to mcp/datanpm test                        # unit, golden and stdio protocol testsclaude mcp add hearth-dev -- node "$PWD/mcp/dist/index.js"

The server reuses the site's own logic from src/lib, so search behaves the same way in both.

Golden queries

mcp/golden/ holds real analyst questions and the hunts a good answer must include. Adding one is the most useful way to improve search. See golden/README.md.

Releasing

Maintainers only:

1. Bump version in mcp/package.json, mcp/server.json and the pinned example under Locked-down setup in this README. A test fails if any of them differ.
2. Merge to main.
3. Push a tag named mcp-v<version>, for example mcp-v0.1.0.

The publish workflow then:

1. Waits for approval in the npm-publish environment.
2. Publishes to npm with provenance, using trusted publishing (no npm token is stored).
3. Waits for npm to serve the new version, which can take several minutes.
4. Lists the release in the MCP Registry as io.github.THORCollective/hearth.

If the run fails after the npm publish, use Re-run failed jobs. A version already on npm is never published twice, so the re-run picks up at the registry step.