Shodan

io.github.w0h1vPublished by GitHub account w0h1vv1.0.37Updated Nov 5, 2026

MCP server for Shodan API — device search, IP and domain recon, DNS, and CVE/CPE queries.

VerifiedSTDIODesktop onlyWeb Search & ScrapingSecurity & Monitoring

Overview

AI-generated overview

Shodan MCP server that lets an assistant look up hosts, search internet-connected devices, resolve DNS, and query CVE/CPE vulnerability data.

What you can do
  • Look up a single IP for open ports, services, CVEs, TLS certificates, location and cloud details
  • Search Shodan's device database with query syntax, paging and facet breakdowns, or get free match counts
  • Enumerate subdomains and DNS records for a domain, and resolve hostnames to IPs or IPs to hostnames in batch
  • Query CVEDB for CVE details with CVSS, EPSS and KEV status, find CPE identifiers, and list CVEs by product or CPE
  • Check the API plan and remaining query and scan credits, and list valid search filters and facets
When to use it
Useful for security and network reconnaissance work: sizing exposure of an IP or domain, checking whether a CVE is exploited in the wild, or finding affected products and versions. Also handy for asset discovery and vulnerability triage inside an assistant conversation.
Requirements
Runs locally as a Node.js package (Node.js 20 or newer) over stdio, or as an HTTP streaming service when MCP_TRANSPORT is set. Requires a Shodan API key in the SHODAN_API_KEY environment variable and network access to Shodan. Filtered searches need a membership or paid API plan.
Before you install
The Shodan API key is a billable credential: filtered shodan_search queries and domain_info calls consume query credits, so a misused key can spend your plan. The optional HTTP transport has no authentication, so anyone who can reach the port can spend credits; keep it on localhost or behind an authenticating proxy. Lookups are sent to Shodan, and the key is sent to api.shodan.io. Tools are read-only.

Installation

In SourceWeft

  1. Open Shodan in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[MCP Shodan: network intelligence for AI agents. Internet reconnaissance, DNS intelligence and CVE analysis over the Model Context Protocol.]

[npm version] [CI] [License: MIT] [Node 20 or newer] [MCP Registry]

Quickstart · Tools · HTTP · Security · Troubleshooting · Docs

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 own Shodan 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.

How it works

mermaid
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.

sh
# Claude Codeclaude mcp add --transport stdio --env SHODAN_API_KEY=your-key shodan -- npx -y @burtthecoder/mcp-shodan
# Codex CLIcodex mcp add shodan --env SHODAN_API_KEY=your-key -- npx -y @burtthecoder/mcp-shodan
# Gemini CLIgemini 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.

GroupToolWhat it does
Networkip_lookupPorts, products, CVEs, TLS, location and cloud for one IP, optionally with banner history
shodan_searchSearch devices with Shodan query syntax, with paging and facet breakdowns
shodan_countTotal matches and facet breakdowns for a query, without results (free)
domain_infoSubdomains and DNS records for a domain
dns_lookupResolve hostnames to IPs, in batch
reverse_dns_lookupHostnames for IPs, in batch
Vulnerabilities (CVEDB)cve_lookupCVSS, EPSS, KEV, references and affected CPEs for one CVE
cpe_lookupCPE 2.3 identifiers for a product name
cves_by_productCVEs for a product or CPE, filterable by KEV and date, sortable by EPSS
Helperssearch_filtersValid search filter and facet names
api_infoYour plan and remaining query and scan credits

[!TIP] Credits: filtered shodan_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:

sh
MCP_TRANSPORT=httpStream MCP_PORT=3000 SHODAN_API_KEY=your-key node build/index.js
sh
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

VariableDefaultDescription
SHODAN_API_KEY(required)Your Shodan API key
MCP_TRANSPORTstdiostdio or httpStream
MCP_HOSTlocalhostBind address (httpStream only). The Docker image sets 0.0.0.0
MCP_PORT3000HTTP port (httpStream only)
MCP_ENDPOINT/mcpHTTP endpoint path (httpStream only)

Security

[!WARNING] The HTTP transport has no 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

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

See CONTRIBUTING.md and the changelog.

License

MIT. See LICENSE.

Source: README.md at commit 422483a

Tools

11

ip_lookup

Retrieve comprehensive information about an IP address, including geolocation, operating system, open ports, running services (product, version, CPE), known vulnerabilities (CVEs), SSL certificates, hostnames, and cloud provider details if available. Returns service banners and HTTP server information when present. Optional history returns historical banners; minify omits banners.

Parametersiprequiredminifyhistory

cve_lookup

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

Parameterscverequired

dns_lookup

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.

Parametershostnamesrequired

reverse_dns_lookup

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.

Parametersipsrequired

cpe_lookup

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.

Parametersskipcountlimitproductrequired

cves_by_product

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.

Parametersskipcountcpe23limitis_kevproductend_datestart_datesort_by_epss

shodan_count

Get the total number of Shodan results for a query, with optional facet breakdowns (e.g. by country, org, port). Free: does not consume query credits. Use search_filters to list valid filters and facets.

Parametersqueryrequiredfacets

domain_info

Get subdomains and DNS records for a domain from Shodan. Costs 1 query credit per lookup.

Parameterspagetypedomainrequiredhistory

api_info

Show the Shodan API plan, remaining query and scan credits, monitored IPs, and usage limits for the configured API key. Free: does not consume credits.

Takes no parameters.

search_filters

List the search filters and facets Shodan supports. Use this to build valid shodan_search and shodan_count queries and facets. Free: does not consume credits.

Takes no parameters.

Version history

3
  1. v1.0.37LatestNov 5, 2026
  2. v1.0.34Oct 12, 2026
  3. v1.0.31Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts