Shodan MCP Server

A Model Context Protocol (MCP) server that provides network intelligence and vulnerability research tools powered by the Shodan API and Shodan CVEDB. Query IP addresses, search internet-connected devices, resolve DNS, and look up CVEs directly from your AI assistant.

Quick Start

Claude Desktop (stdio)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "shodan": {
      "command": "npx",
      "args": ["-y", "@tocharianou/mcp-shodan"],
      "env": {
        "SHODAN_API_KEY": "<your-api-key>"
      }
    }
  }
}

Get your API key at account.shodan.io.

HTTP / Streamable mode

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 SHODAN_API_KEY=<key> npx @tocharianou/mcp-shodan

Then point your MCP client at http://localhost:3001/mcp.

Features

IP reconnaissance — open ports, running services, banners, SSL certificates, cloud provider detection
Device search — query Shodan's internet-wide scan database with advanced filters and geographic distribution
DNS operations — forward and reverse DNS lookups for domains and IP addresses
Vulnerability intelligence — CVE details (CVSS v2/v3, EPSS, KEV status), CPE lookups, and product-specific CVE tracking via CVEDB

Configuration

Environment variable	Required	Description
`SHODAN_API_KEY`	✓*	Shodan API key, appended as `?key=` query parameter (direct mode)
`SHODAN_BASE_URL`	–	Override API base URL (e.g. proxy endpoint). Default: `https://api.shodan.io`
`SHODAN_AUTH_TOKEN`	✓*	Bearer token for proxy authentication
`SHODAN_CVEDB_URL`	–	Override CVEDB base URL. Default: `https://cvedb.shodan.io`
`SHODAN_TIMEOUT`	–	Request timeout in ms (default: `30000`)
`MCP_TRANSPORT`	–	`stdio` (default) or `http`
`MCP_HTTP_PORT`	–	HTTP server port (default: `3001`)
`MCP_HTTP_HOST`	–	HTTP server host (default: `localhost`)

* Either SHODAN_API_KEY (direct) or SHODAN_BASE_URL + SHODAN_AUTH_TOKEN (proxy) must be set.

Note: The CVEDB endpoints (cve_lookup, cpe_lookup, cves_by_product) are publicly accessible and do not require an API key.

Direct vs Proxy mode

Direct mode — the server calls Shodan directly using your own API key:

SHODAN_API_KEY=YOUR_KEY_HERE

Proxy mode — the server calls a backend gateway that injects the real API key and handles billing. The server authenticates to the gateway using a Bearer token:

SHODAN_BASE_URL=https://gateway.example.com/shodan
SHODAN_AUTH_TOKEN=YOUR_BEARER_TOKEN

The tool itself is mode-agnostic; the calling application sets the appropriate variables.

Available Tools

Tool	Description	Requires paid key
`ip_lookup`	IP address analysis: ports, services, banners, cloud provider, hostnames	✓
`shodan_search`	Search internet-connected devices with country distribution stats	✓
`dns_lookup`	Batch forward DNS resolution (hostnames → IPs)	✓
`reverse_dns_lookup`	Batch reverse DNS lookup (IPs → hostnames)	✓
`cve_lookup`	CVE details: CVSS v2/v3, EPSS, KEV status, ransomware associations	–
`cpe_lookup`	Search CPE entries by product name with pagination	–
`cves_by_product`	All CVEs for a product or CPE 2.3 identifier with filtering	–

Example Queries

"What ports and services are exposed on IP 8.8.8.8?"
"Search Shodan for Apache servers in Germany: apache country:DE"
"Resolve these hostnames to IP addresses: github.com, google.com"
"What is the severity and KEV status of CVE-2021-44228?"
"List all CVEs affecting log4j sorted by EPSS score"

Debugging

Use the MCP Inspector to test and debug:

npm run inspector

Server logs are written to stderr so they do not interfere with the MCP JSON-RPC stream on stdout.

Troubleshooting

Symptom	Likely cause
`Request failed with status code 401`	Invalid or missing `SHODAN_API_KEY`
`Request failed with status code 402`	Out of Shodan query credits
`Request failed with status code 403`	API plan does not support this endpoint (requires paid membership)
`Request failed with status code 429`	Rate limit exceeded
Tool calls time out	Increase `SHODAN_TIMEOUT` or check network connectivity

Development

git clone https://github.com/TocharianOU/mcp-shodan.git
cd mcp-shodan
npm install --ignore-scripts
npm run build
cp .env.example .env   # fill in your API key
npm start

Release

See RELEASE.md for the full release process.

License

Disclaimer: This project is a fork of BurtTheCoder/mcp-shodan, extended with dual-transport support, Hub proxy mode, and TocharianOU project conventions. It is community-maintained and not affiliated with or endorsed by Shodan.

@tocharianou/mcp-shodan

Quick Install