w0h1v/mcp-shodan

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
Quickstart
**Requirements:** Node.js 20 or newer and a Shodan API key.
For Claude Desktop, VS Code, Smithery 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: 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: