shodan — Claude Code MCP server: IP recon and CVE lookups
Gives your agent Shodan: open ports and banners, TLS certificates, DNS records, and vulnerability severity with EPSS and KEV in one call.
claude mcp add shodan -e SHODAN_API_KEY=<SHODAN_API_KEY> -- npx -y @burtthecoder/mcp-shodanWhat shodan does
This server wraps the Shodan API and Shodan CVEDB and exposes eleven read-only tools to an agent. ip_lookup takes an IPv4 or IPv6 address and returns listening ports, products with versions, TLS fingerprints such as JARM and JA3S, plus the cloud it runs in. shodan_search runs Shodan query syntax with paging and facet breakdowns by country, org or port; shodan_count returns just the match total for free.
Vulnerability work sits in three tools. cve_lookup pulls CVSS, EPSS, KEV status and affected CPEs for one CVE, cpe_lookup maps a product name to CPE 2.3 identifiers, and cves_by_product lists CVEs filterable by KEV or date and sortable by EPSS. CVEDB needs no key and burns no query credits. For DNS there is domain_info with subdomains and records, plus batched dns_lookup and reverse_dns_lookup.
You need Node.js 20 or newer and your own Shodan API key; the project is independent and not affiliated with Shodan. Tool arguments pass zod schemas before a request is built, so a malformed IP or CVE id never leaves your machine. Transports: stdio by default, HTTP streaming for a shared service. That HTTP mode ships without authentication, so bind it to localhost or put a proxy in front. Lookups go to Shodan's servers. Filtered searches need a membership or paid plan, and roughly one request per second is the ceiling.
What it helps with
- see which ports and services a given IP exposes
- judge how urgent a CVE is from its EPSS score and KEV listing
- map a domain's subdomains and DNS records
- list CVEs for a product by name or CPE
- size a search query without spending credits
Example prompts for the agent
- Use
shodan_countto total Apache hosts in Germany, broken down by port - Pull subdomains for example.com and resolve them to IPs
How to install shodan
Platform CLI
claude mcp add shodan -e SHODAN_API_KEY=<SHODAN_API_KEY> -- npx -y @burtthecoder/mcp-shodanReplace <…> with your own values
Platform CLI
codex mcp add w0h1v-shodan --env SHODAN_API_KEY=<SHODAN_API_KEY> -- npx -y @burtthecoder/mcp-shodanReplace <…> with your own values
Config file
{
"mcpServers": {
"w0h1v-shodan": {
"command": "npx",
"args": [
"-y",
"@burtthecoder/mcp-shodan"
],
"env": {
"SHODAN_API_KEY": "<SHODAN_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"w0h1v-shodan": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@burtthecoder/mcp-shodan"
],
"env": {
"SHODAN_API_KEY": "<SHODAN_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e SHODAN_API_KEY=<SHODAN_API_KEY> w0h1v-shodan npx -y @burtthecoder/mcp-shodanReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about shodan
How do I install shodan in Claude Code?
Run claude mcp add shodan -e SHODAN_API_KEY=<SHODAN_API_KEY> -- npx -y @burtthecoder/mcp-shodan. The alternative spelling with an explicit transport is claude mcp add --env SHODAN_API_KEY=<SHODAN_API_KEY> --transport stdio w0h1v-shodan -- npx -y @burtthecoder/mcp-shodan.
What does shodan do?
It connects an agent to the Shodan API and CVEDB for host recon, device search, DNS and vulnerability data. Every tool reads; nothing is written back.
Why does shodan_search return 403?
Search filters require a membership or paid API plan. Call api_info to check your plan and remaining credits.
