Skip to main content
Glama
Sign In
enesjakozh
mcp-shodan

mcp-shodan

by w0h1v
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-shodan is an MCP server that gives AI agents access to the Shodan API and Shodan CVEDB. Hand your agent an IP, hostname, search query, product or CVE and get back what an analyst would look at: open ports and banners, TLS certificates, DNS, and vulnerability severity with EPSS and KEV status.

NOTE

Independent project, not affiliated with Shodan. You need your ownShodan API key.

Highlights

  • Host reconnaissance. Open ports, products and versions, known CVEs, TLS certificate details (fingerprint, JARM, JA3S), cloud provider and banner history for any IPv4 or IPv6 address.

  • Device search. Shodan query syntax with paging and facet breakdowns (country, org, port, vuln and more), plus a free count-only mode for sizing a query.

  • Vulnerability intelligence. CVE details with CVSS v4/v3/v2, EPSS and KEV; CVEs by product or CPE, sortable by EPSS. CVEDB is free and doesn't spend query credits.

  • DNS. Subdomains and DNS records for a domain, and forward and reverse lookups for many names or IPs in one call.

  • Credit-aware. Free tools are marked as free, and api_info shows the credits left on your plan.

  • Two transports. stdio for desktop clients, HTTP streaming for a shared service.

  • Tested. Unit tests with a mocked Shodan API run in CI on Node 20, 22 and 24.

Related MCP server: Shodan-MCP-Server

How it works

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-shodan"]
    S -->|"validate input,<br/>HTTPS + API key"| SH["Shodan REST API"]
    S -->|"HTTPS, no key"| C["Shodan CVEDB"]
    SH -->|"JSON"| S
    C -->|"JSON"| S
    S -->|"structured JSON text"| A

Quickstart

Requirements: Node.js 20 or newer and a Shodan API key.

# Claude Code
claude mcp add --transport stdio --env SHODAN_API_KEY=your-key shodan -- npx -y @burtthecoder/mcp-shodan

# Codex CLI
codex mcp add shodan --env SHODAN_API_KEY=your-key -- npx -y @burtthecoder/mcp-shodan

# Gemini CLI
gemini mcp add -e SHODAN_API_KEY=your-key shodan npx -y @burtthecoder/mcp-shodan

For Claude Desktop, VS Code and running from source, see Connect a client.

Then ask your agent: "What is exposed on 8.8.8.8, and is CVE-2021-44228 in the KEV catalog?" More prompts are in example workflows.

Tools

Eleven read-only tools. Full parameters are in the tool reference.

Group

Tool

What it does

Network

ip_lookup

Ports, products, CVEs, TLS, location and cloud for one IP, optionally with banner history

shodan_search

Search devices with Shodan query syntax, with paging and facet breakdowns

shodan_count

Total matches and facet breakdowns for a query, without results (free)

domain_info

Subdomains and DNS records for a domain

dns_lookup

Resolve hostnames to IPs, in batch

reverse_dns_lookup

Hostnames for IPs, in batch

Vulnerabilities (CVEDB)

cve_lookup

CVSS, EPSS, KEV, references and affected CPEs for one CVE

cpe_lookup

CPE 2.3 identifiers for a product name

cves_by_product

CVEs for a product or CPE, filterable by KEV and date, sortable by EPSS

Helpers

search_filters

Valid search filter and facet names

api_info

Your plan and remaining query and scan credits

TIP

Credits: filteredshodan_search queries cost one query credit (plus one per extra page) and domain_info costs one per call. shodan_count, ip_lookup, dns_lookup, reverse_dns_lookup, search_filters, api_info and the CVEDB tools are free.

HTTP streaming transport

stdio is the default. Set MCP_TRANSPORT=httpStream to run a standalone HTTP service:

MCP_TRANSPORT=httpStream MCP_PORT=3000 SHODAN_API_KEY=your-key node build/index.js
docker build -t mcp-shodan .
docker run -p 127.0.0.1:3000:3000 -e SHODAN_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-shodan

A health check is served at /health.

Environment variables

Variable

Default

Description

SHODAN_API_KEY

(required)

Your Shodan API key

MCP_TRANSPORT

stdio

stdio or httpStream

MCP_HOST

localhost

Bind address (httpStream only). The Docker image sets 0.0.0.0

MCP_PORT

3000

HTTP port (httpStream only)

MCP_ENDPOINT

/mcp

HTTP endpoint path (httpStream only)

Security

WARNING

The HTTP transport hasno authentication. Keep the port on localhost or behind an authenticating reverse proxy, or anyone who can reach it can spend your query credits.

  • Tool arguments are validated with zod schemas before any request is built. IPs must be valid IPv4 or IPv6, domains valid hostnames, facets name[:count] lists, and CVE IDs must match CVE-YYYY-NNNN.

  • The API key is read from the environment and sent only to api.shodan.io. CVEDB calls carry no key.

  • What you look up is sent to Shodan.

Report vulnerabilities privately; see SECURITY.md.

Troubleshooting

  • 401 / invalid key: check for spaces or quotes around the key, then restart the client. curl "https://api.shodan.io/api-info?key=$SHODAN_API_KEY" shows your plan and credits.

  • 403 on shodan_search: search filters need a membership or paid API plan. Run api_info to see your plan and credits.

  • 429: Shodan allows about one request per second. Retry after a moment.

More in the troubleshooting guide.

Development

git clone https://github.com/w0h1v/mcp-shodan && cd mcp-shodan
npm ci
npm test                          # build + unit tests, no key or network
npx fastmcp dev build/index.js    # try tools interactively (needs SHODAN_API_KEY)

See CONTRIBUTING.md and the changelog.

License

MIT. See LICENSE.

Available Tools

7 tools
cpe_lookupA
Read-only

Search for Common Platform Enumeration (CPE) entries by product name in Shodan's CVEDB. Supports pagination and can return either full CPE details or just the total count. Useful for identifying specific versions and configurations of software and hardware.

Inputs: product (required), skip, count, limit.

cve_lookupA
Read-only

Query detailed vulnerability information from Shodan's CVEDB. Returns comprehensive CVE details including CVSS scores (v2/v3), EPSS probability and ranking, KEV status, proposed mitigations, ransomware associations, and affected products (CPEs).

Inputs: cve (required).

cves_by_productA
Read-only

Search for vulnerabilities affecting specific products or CPEs. Supports filtering by KEV status, sorting by EPSS score, date ranges, and pagination. Can search by product name or CPE 2.3 identifier. Returns detailed vulnerability information including severity scores and impact assessments.

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

dns_lookupA
Read-only

Resolve domain names to IP addresses using Shodan's DNS service. Supports batch resolution of multiple hostnames in a single query. Returns IP addresses mapped to their corresponding hostnames.

Inputs: hostnames (required).

ip_lookupA
Read-only

Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available. Returns service banners and HTTP server information when present.

Inputs: ip (required).

reverse_dns_lookupA
Read-only

Perform reverse DNS lookups to find hostnames associated with IP addresses. Supports batch lookups of multiple IP addresses in a single query. Returns all known hostnames for each IP address, with clear indication when no hostnames are found.

Inputs: ips (required).

shodan_searchB
Read-only

Search Shodan's database of internet-connected devices. Returns detailed information about matching devices including services, vulnerabilities, and geographic distribution. Supports advanced search filters and returns country-based statistics.

Inputs: query (required), max_results.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools are clearly distinct: ip_lookup, shodan_search, dns_lookup, and reverse_dns_lookup each target a different resource. However, cve_lookup and cves_by_product both return vulnerability information, which could cause some confusion despite their different query approaches.

    Naming Consistency4/5

    Tool names mostly follow a consistent noun-based pattern (ip_lookup, dns_lookup, cve_lookup, cpe_lookup) with descriptive compound names for searches. The mix of 'lookup' and 'search' verbs is a minor inconsistency, but the pattern is still predictable and readable.

    Tool Count5/5

    Seven tools is well-scoped for a Shodan-focused server, covering IP intelligence, device search, DNS, and vulnerability data without unnecessary bloat. Each tool serves a distinct purpose within the security research domain.

    Completeness4/5

    The tool set covers core Shodan functionality: IP lookup, device search, DNS resolution, and CVE/CPE vulnerability research. Minor gaps exist such as account/API info or network/port-specific queries, but the primary workflows for security research are well covered.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Shodan MCP Server

      X3r0K
      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
      -

    • Shodan-MCP-Server

      X3r0K
      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
      -

    Appeared in Searches