Skip to main content
Glama

Shodan MCP Server

Give MCP clients (Cursor, Claude Desktop, VS Code, Codex, and others) full access to Shodan — host recon, banner search, DNS, CVEs, on-demand scans, and network alerts.

Independent project. Not affiliated with Shodan.

What it does

  • 47 tools covering Shodan REST, InternetDB, CVEDB, and the Exploits API

  • Resources for account credits, search filters/facets, ports, protocols, and alert triggers

  • Prompts for host recon, exposure search, domain mapping, and CVE triage

  • Compact summaries by default so models see ports/products/vulns instead of raw banner dumps

  • Credit warnings on searches that spend query credits

  • Scan confirmations (confirm=true, plus confirm_large / confirm_internet for wide targets)

  • stdio for desktop clients, Streamable HTTP for a shared process

  • InternetDB and CVEDB work without an API key

Use this only against assets you are authorized to assess. Shodan's terms of service apply to every request.

Related MCP server: offsec-mcp

Requirements

  • Node.js 20 or later

  • A Shodan API key from account.shodan.io for REST/DNS/scans/alerts/exploits

Install

git clone https://github.com/k3nn3dy-ai/Shodan-MCP.git
cd Shodan-MCP
npm install
npm run build

Copy .env.example and export the key (do not commit it):

export SHODAN_API_KEY=your-key

MCP client config

Point the client at dist/index.js. stdio is the default.

Cursor / Claude Desktop / Claude Code

{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/Shodan-MCP/dist/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-key"
      }
    }
  }
}

Docker

docker build -t shodan-mcp .
{
  "mcpServers": {
    "shodan": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-key"
      }
    }
  }
}

HTTP transport

node dist/index.js --http --port 48731

MCP endpoint: http://127.0.0.1:48731/mcp
Health check: http://127.0.0.1:48731/health

Bind stays on localhost unless you pass --host. There is no built-in auth on HTTP — do not expose it to the internet.

Tools

Free without a key:

Tool

Purpose

shodan_internetdb

Fast IP enrichment (ports, CPEs, tags, CVE ids)

shodan_cve

CVE details (CVSS, EPSS, KEV, CPEs)

shodan_cves

Search CVEs by product or CPE 2.3

shodan_cpes

CPE dictionary lookup

REST (API key):

Tool

Purpose

Credits

shodan_host

Host card for an IP

none

shodan_search

Banner search

1 if filters or page > 1

shodan_count

Match count + facets

none

shodan_search_tokens

Parse a query

none

shodan_search_facets / shodan_search_filters

Catalog

none

shodan_dns_domain

Subdomains + records

none

shodan_dns_resolve / shodan_dns_reverse

Forward / reverse DNS

none

shodan_my_ip

Egress IP Shodan sees

none

shodan_ports / shodan_protocols / shodan_services

Crawler catalogs

none

shodan_honeyscore

Labs honeypot probability

none

shodan_api_info / shodan_profile / shodan_org

Plan, credits, org

none

shodan_scan

On-demand crawl of IPs/CIDRs

1 scan credit per IP

shodan_scan_status / shodan_scans

Scan progress

none

shodan_scan_internet

Enterprise Internet-wide scan

scan credits

shodan_alert_*

Network alerts and triggers

plan-dependent

shodan_notifier_*

Notifier CRUD

plan-dependent

shodan_query_*

Community saved-query directory

none

shodan_datasets / shodan_dataset_files

Bulk data listings

plan-dependent

shodan_exploits / shodan_exploit_count

Exploit archive

none

Host and search tools return a compact summary unless you set summary=false. Scans require confirm=true. CIDRs wider than /24 also need confirm_large=true.

Prompts

  • recon_host — InternetDB → host lookup → CVE triage for one IP

  • search_exposure — tokenize, count/facet, then one search page

  • domain_osint — domain DNS then enrich resolved IPs

  • vuln_triage — CVEDB + exploits + optional exposure count

Development

npm test
npm run typecheck
npm run dev          # stdio
npm run dev:http     # http://127.0.0.1:48731

Tests mock the Shodan HTTP APIs. They do not spend credits.

Configuration

Variable

Default

Meaning

SHODAN_API_KEY

unset

REST / exploits key

SHODAN_BASE_URL

https://api.shodan.io

REST origin

SHODAN_TIMEOUT_MS

30000

Per-request timeout

SHODAN_MAX_RESPONSE_BYTES

524288

Truncate oversized JSON

API keys are query parameters on Shodan's side. This server never prints them: errors redact key=....

License

MIT

Available Tools

47 tools
shodan_alert_add_notifierAttach notifier to alertC

Attach a notifier id to an alert (use 'default' for email).

Inputs: id (required), notifier_id (required).

shodan_alert_createCreate network alertB

Monitor an IP or netblock for new services and vulnerabilities. Body matches the Shodan alert API: { name, filters: { ip: [...] }, expires? }.

Inputs: ip (required), name (required), expires.

shodan_alert_deleteDelete alertB
DestructiveIdempotent

Delete a network alert by id.

Inputs: id (required).

shodan_alert_disable_triggerDisable alert triggerC
DestructiveIdempotent

Disable a trigger on an alert.

Inputs: id (required), trigger (required).

shodan_alert_enable_triggerEnable alert triggerC

Enable one or more comma-separated triggers on an alert.

Inputs: id (required), triggers (required).

shodan_alert_getGet alertB
Read-onlyIdempotent

Get one network alert by id.

Inputs: id (required).

shodan_alert_listList alertsA
Read-onlyIdempotent

List network alerts on the account.

Inputs: no named parameters.

shodan_alert_remove_notifierDetach notifier from alertC
DestructiveIdempotent

Remove a notifier from an alert.

Inputs: id (required), notifier_id (required).

shodan_alert_triggersList alert triggersA
Read-onlyIdempotent

List trigger types that can be enabled on a network alert.

Inputs: no named parameters.

shodan_alert_updateUpdate alertC

Replace the name/filters on an existing alert.

Inputs: id (required), ip (required), name (required), expires.

shodan_api_infoAPI plan and creditsA
Read-onlyIdempotent

Show the authenticated plan, query credits remaining, and scan credits remaining.

Inputs: no named parameters.

shodan_countCount search resultsA
Read-onlyIdempotent

Return how many banners match a query, plus optional facets. Does not spend query credits and does not return hosts. Use this before shodan_search.

Inputs: query (required), facets.

shodan_cpesSearch CPEsB
Read-onlyIdempotent

Look up CPE 2.3 identifiers for a product name via CVEDB. Free, no API key.

Inputs: product (required), skip, limit.

shodan_cveCVE lookupA
Read-onlyIdempotent

Look up a CVE in Shodan CVEDB (free, no API key): CVSS, EPSS, KEV, CPEs, references.

Inputs: cve (required).

shodan_cvesSearch CVEsA
Read-onlyIdempotent

Search CVEDB by product or CPE 2.3. Optional KEV filter and EPSS sort. Free, no API key. Do not pass product and cpe23 together.

Inputs: skip, count, cpe23, limit, +5 more.

shodan_dataset_filesDataset filesB
Read-onlyIdempotent

List files inside a named bulk dataset.

Inputs: dataset (required).

shodan_datasetsList datasetsB
Read-onlyIdempotent

List bulk data filesets available to the account.

Inputs: no named parameters.

shodan_dns_domainDomain DNSB
Read-onlyIdempotent

Return subdomains and DNS records Shodan knows for a domain.

Inputs: domain (required), page, type, history.

shodan_dns_resolveForward DNSB
Read-onlyIdempotent

Resolve hostnames to IPs. Comma-separated list.

Inputs: hostnames (required).

shodan_dns_reverseReverse DNSB
Read-onlyIdempotent

Resolve IPs to hostnames. Comma-separated list.

Inputs: ips (required).

shodan_exploit_countCount exploitsB
Read-onlyIdempotent

Count matching exploits without returning the full result set.

Inputs: query (required), facets.

shodan_exploitsSearch exploitsB
Read-onlyIdempotent

Search the Shodan Exploits archive (requires API key). Query filters include cve, type, platform, port, author.

Inputs: query (required), page, facets.

shodan_honeyscoreHoneypot scoreB
Read-onlyIdempotent

Labs honeypot probability for an IP, from 0.0 (not a honeypot) to 1.0.

Inputs: ip (required).

shodan_hostHost lookupA
Read-onlyIdempotent

Look up an IPv4/IPv6 address in Shodan. Default response is a compact analyst summary (org, ports, products, vulns). Set summary=false for the raw banner record. Host lookups do not spend query credits.

Inputs: ip (required), minify, history, summary, +1 more.

shodan_internetdbInternetDB lookupA
Read-onlyIdempotent

Free, keyless IP enrichment from internetdb.shodan.io: ports, CPEs, hostnames, tags, and CVE ids. Weekly data, no banners. Accepts a single IP or a comma-separated list (max 25).

Inputs: ip (required).

shodan_my_ipMy public IPA
Read-onlyIdempotent

Return the public IP address Shodan sees for this client.

Inputs: no named parameters.

shodan_notifier_createCreate notifierB

Create a notifier. Provider-specific fields go in args (e.g. to=email@domain for email).

Inputs: provider (required), args, description.

shodan_notifier_deleteDelete notifierC
DestructiveIdempotent

Delete a notifier by id.

Inputs: id (required).

shodan_notifier_getGet notifierC
Read-onlyIdempotent

Get one notifier by id.

Inputs: id (required).

shodan_notifier_providersNotifier providersA
Read-onlyIdempotent

List notifier providers and the arguments they require.

Inputs: no named parameters.

shodan_notifiersList notifiersA
Read-onlyIdempotent

List notifiers configured on the account.

Inputs: no named parameters.

shodan_orgOrganizationB
Read-onlyIdempotent

Return organization membership for the API key, if any.

Inputs: no named parameters.

shodan_portsCrawled portsB
Read-onlyIdempotent

List ports Shodan crawlers currently scan.

Inputs: no named parameters.

shodan_profileAccount profileA
Read-onlyIdempotent

Return the Shodan account profile for the configured API key.

Inputs: no named parameters.

shodan_protocolsScan protocolsA
Read-onlyIdempotent

List protocols available for on-demand Internet scans.

Inputs: no named parameters.

shodan_query_listSaved query directoryC
Read-onlyIdempotent

List shared community search queries.

Inputs: page, sort, order.

shodan_query_tagsSaved query tagsB
Read-onlyIdempotent

List popular tags on the community query directory.

Inputs: size.

shodan_scanOn-demand scanA

Ask Shodan to crawl IPs or CIDRs. Requires confirm=true. CIDRs wider than /24 also need confirm_large=true. Each IP spends 1 scan credit. Paid plan required.

Inputs: ips (required), confirm (required), confirm_large.

shodan_scan_internetInternet-wide scanB

Enterprise-only: crawl the Internet for one port/protocol. Requires confirm=true and confirm_internet=true.

Inputs: port (required), confirm (required), protocol (required), confirm_internet (required).

shodan_scansList scansA
Read-onlyIdempotent

List on-demand scans submitted by this account.

Inputs: no named parameters.

shodan_scan_statusScan statusB
Read-onlyIdempotent

Get progress for an on-demand scan id.

Inputs: id (required).

shodan_search_facetsList search facetsA
Read-onlyIdempotent

List facet names that can summarize search results.

Inputs: no named parameters.

shodan_search_filtersList search filtersB
Read-onlyIdempotent

List filter names accepted in Shodan search queries.

Inputs: no named parameters.

shodan_search_tokensParse search queryA
Read-onlyIdempotent

Break a Shodan query into filters, attributes, and leftover free-text. Useful to verify query syntax before spending credits.

Inputs: query (required).

shodan_servicesService namesB
Read-onlyIdempotent

Map of port to named service for Shodan crawlers.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 47 tools

    Disambiguation4/5

    Most tools target distinct Shodan resources and actions, with clear separation between search, count, host lookup, DNS, scans, alerts, notifiers, datasets, CVEDB, and exploits. A few boundaries are softer—shodan_host vs. shodan_internetdb both enrich IPs, and cve/cves/cpes and exploits/exploit_count are closely related—but the descriptions generally clarify intended use.

    Naming Consistency5/5

    All tools use a consistent shodan_ prefix with snake_case names and mostly predictable noun or noun_action ordering (e.g., shodan_alert_create, shodan_notifier_delete, shodan_dns_resolve). Plural forms for list endpoints are used consistently enough that the pattern remains easy to follow.

    Tool Count2/5

    47 tools is very large for an MCP server and creates a heavy selection burden for an agent, even though Shodan's API is broad. The surface spans many subdomains, but the count is well beyond the range where tools are easy to scan and choose among.

    Completeness4/5

    Coverage is strong across search, host intelligence, DNS, scanning, alerts with triggers and notifiers, community queries, datasets, CVEDB, and exploits. Minor gaps may exist around streaming or other specialized Shodan APIs, but the major workflows are well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers