Skip to main content
Glama

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)

Related MCP server: Shodan MCP Server

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.

Parameter

Type

Default

Description

target

string

—

Domain, URL, or fuzzy name

show_banners

bool

false

Include raw service banners (first 3 lines)

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"


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

Parameter

Type

Default

Description

target

str

—

Domain, URL, or keyword

max_results

int

5

Max hosts (cap: 20)

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.

Parameter

Type

Description

target

str

Domain or keyword

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

Plan

shodan_host

shodan_search

shodan_dns

Free

✅

✅ (limited)

❌

Membership

✅

✅

✅

API (paid)

✅

✅

✅

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for querying the Shodan API and Shodan CVEDB. This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more.
      7
      191
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A WebSocket server that provides MCP interface for searching and retrieving information about internet-connected devices, IP addresses, DNS data, and CVE vulnerabilities through the Shodan API.
      3
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      This is a Model Context Protocol (MCP) server that provides access to the Shodan API. It allows you to programmatically query Shodan for information about devices, vulnerabilities, and more.
      2
      -