shodan-mcp

A minimal Model Context Protocol server for Shodan. It exposes only the endpoints needed for two things: checking what your own infrastructure exposes to the internet, and searching Shodan's data for general reconnaissance. One file, no extra dependencies beyond the official MCP SDK.

Quick start

git clone https://github.com/aethrox/shodan-mcp.git
cd shodan-mcp
npm install

Register it with Claude Code:

claude mcp add shodan -s user -e SHODAN_API_KEY=your-key-here -- node /absolute/path/to/index.js

Or run it standalone (it speaks MCP over stdio):

SHODAN_API_KEY=your-key-here node index.js

A Shodan API key is required either way. Instead of exporting SHODAN_API_KEY yourself, you can copy .env.example to .env and put the key there; the server loads it automatically on startup. .env is gitignored, so it never gets committed.

cp .env.example .env
# then edit .env and set SHODAN_API_KEY

Tools

Tool	What it does
shodan_my_ip	Public IP Shodan sees this API key's requests coming from. Starting point for scanning your own infrastructure.
shodan_host_lookup	Full Shodan record for one IP: open ports, banners, detected products/versions, known vulnerabilities.
shodan_search	Search Shodan's device database using Shodan search syntax (country:, net:, vuln:, ...).
shodan_cve_lookup	CVE details from Shodan's CVEDB: CVSS score, affected CPEs, how many exposed hosts Shodan currently sees.
shodan_cves_by_product	CVEs affecting a given CPE (product + version).
shodan_host_count	Count hosts matching a search query without spending query credits.
shodan_search_filters	List the search filters Shodan supports (country, port, net, vuln, ...).
shodan_dns_domain	Subdomains and DNS entries Shodan has seen for a domain.
shodan_dns_resolve	Resolve hostnames to IP addresses.
shodan_dns_reverse	Reverse-resolve IP addresses to hostnames.
shodan_account_info	This API key's plan and remaining query/scan credits.

Requirements

• Node.js 20+
• A Shodan API key with the plan tier needed for the endpoints you use (host lookup and search require more than the free tier)

Limitations

• No caching or rate-limit handling: requests go straight to the Shodan API, so hitting your plan's rate limit surfaces as a raw API error.
• No pagination helper for shodan_search; multi-page results need repeated calls with the page argument.
• The API key is passed as a plain environment variable to the MCP process, same as any other stdio MCP server. Don't commit it, and be mindful of where your MCP client config file (e.g. claude mcp add output) ends up stored.

License

MIT