nuclei-mcp

A scoped Nuclei MCP server that refuses to scan anything not found in your HackerOne scope snapshots. Works as a companion to h1-scope-watcher.

Architecture

Copilot/Claude (AI agent)
    │
    │  MCP (stdio)
    ▼
nuclei-mcp container
    │  reads scope
    ├──────────────────► /data/snapshots/*.json  ◄─── h1-scope-watcher writes here
    │  runs scan
    └──────────────────► nuclei binary (built-in)

The two containers share the same host directory mounted as a volume. h1-scope-watcher keeps the JSON files up to date; nuclei-mcp only reads them.

Scope Gate — How It Works

Every call to nuclei_scan or check_scope runs this logic before touching the network:

1. Load all *.json files from /data/snapshots

2. Try exact hostname match (e.g. api.life360.com → matches api.life360.com)

3. Try wildcard match (e.g. sub.tile.com → matches *.tile.com)

4. Try fuzzy keyword match (e.g. life360 → finds api.life360.com, api-cloudfront.life360.com)

5. Check eligible_for_bounty == true AND eligible_for_submission == true

6. Block if any check fails — no exception, no override

Quick Start

1. Build the image

cd nuclei-mcp
docker build -t nuclei-mcp .

2. Add to your Claude/Copilot MCP config

Open claude_desktop_config.json (or equivalent) mcp-config.json (copilot) and add:

{
  "mcpServers": {
    "h1-scope-watcher": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "D:/projects/H1-Scope-Watcher/snapshots:/data/snapshots",
        "-e", "SNAPSHOTS_DIR=/data/snapshots",
        "mcp/h1-scope"
      ]
    },
    "nuclei-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "D:/projects/H1-Scope-Watcher/snapshots:/data/snapshots",
        "-e", "SNAPSHOTS_DIR=/data/snapshots",
        "nuclei-mcp"
      ]
    }
  }
}

Key point: Both containers mount the exact same host path (D:/projects/H1-Scope-Watcher/snapshots) so they share the scope data without any extra networking or IPC.

H1-Scope-Watcher

MCP Tools

nuclei_scan

Run a Nuclei scan — scope-gated.

Example prompts:

• "Run nuclei on life360"

• "Scan api.tile.com for critical and high findings"

• "Run nuclei on production.tile-api.com with cve templates only"

check_scope

Preview the scope gate result without scanning.

Example prompts:

• "Is tile.com in scope?"

• "Check if snipeit.corp.tile.com is bounty eligible" → will show BLOCKED

list_programs

Show all assets from all snapshot files, grouped by eligibility.

Environment Variables

Scope Behaviour Reference

From tile.com program example:

Legal

Only scan targets you own or have explicit written permission to test. This tool does not grant any authorisation — your HackerOne programme agreement is the authorisation document.