shodan-mcp

Passive reconnaissance MCP server powered by Shodan. Scope-gated against your HackerOne snapshots — identical gate to nuclei-mcp.

Passive only — Shodan queries never send a packet to your target. All data comes from Shodan's pre-existing internet-wide scan index.

Architecture

Claude/copilot (AI agent)
    │
    │  MCP (stdio)
    ▼
shodan-mcp container
    ├── reads scope ──► /data/snapshots/*.json  ◄─── h1-scope-watcher
    └── queries     ──► api.shodan.io  (passive, no target contact)

Scope Gate

Every tool runs the same gate as nuclei-mcp:

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

2. Exact → wildcard → fuzzy keyword match

3. Check eligible_for_bounty AND eligible_for_submission

4. Block if either is false — no override

H1-Scope-Watcher

Quick Start

1. Build

cd shodan-mcp
docker build -t shodan-mcp .

2. Add to Claude/Copilot MCP config

{
  "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"
      ]
    },
    "shodan-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "D:/projects/H1-Scope-Watcher/snapshots:/data/snapshots",
        "-e", "SNAPSHOTS_DIR=/data/snapshots",
        "-e", "SHODAN_API_KEY=YOUR_KEY_HERE",
        "shodan-mcp"
      ]
    }
  }
}

Replace YOUR_KEY_HERE with your key from https://account.shodan.io

MCP Tools

shodan_host

Resolve target → IP(s) → full Shodan host report.

What you get per IP:

• Open ports + transport protocol

• Service / product / version fingerprint

• CPE identifiers

• CVE list with CVSS scores and summaries

• ASN, ISP, org, geolocation, OS

• Shodan tags (e.g. cloud, self-signed, vpn)

Example prompts:

• "Run shodan on dummy-target"

• "What ports does api.tile.com expose on Shodan?"

• "Check shodan for production.tile-api.com with banners"

shodan_search

Search Shodan's hostname: index — finds records across ALL IPs that have ever served the hostname, including old/shadow infrastructure.

Example prompts:

• "Search Shodan for dummy-target — show me 10 results"

• "Any forgotten infrastructure for tile.com on Shodan?"

shodan_dns

Pull Shodan's passive DNS records — all subdomains, A/CNAME/MX/TXT Shodan has ever observed for a root domain.

Example prompts:

• "What subdomains does Shodan know about for dummy-target?"

• "Show me Shodan DNS records for tile.com"

check_scope

Preview scope gate without any API call.

list_programs

List all H1 scope assets grouped by bounty eligibility.

Shodan Plan Notes

shodan_dns requires a paid Shodan plan. The server validates your key and plan at startup and logs the result.

Chained Workflow Example

You: "Full passive recon on dummy-target"

Claude/Copilot:
  1. check_scope("dummy-target")
    → ✅ api.dummy-target.com, api-cloudfront.dummy-target.com

  2. shodan_dns("dummy-target")
    → 14 subdomains discovered passively

  3. shodan_host("api.dummy-target.com")
    → Port 443 (nginx 1.18), Port 8443 (unknown)
    → CVE-2021-23017 CVSS 7.7 (nginx)

  4. shodan_search("dummy-target", max_results=10)
    → 3 IPs, one on non-standard port 9200 (Elasticsearch!)

  5. nuclei_scan("api.dummy-target.com")
    → Confirms Elasticsearch exposure

Zero packets sent to the dummy target until step 5.