Shodan MCP Server -- AI-Powered Internet Intelligence for Claude, Cursor & VS Code

shodan-mcp is a Model Context Protocol (MCP) server that gives AI agents like Claude, Cursor, and GitHub Copilot direct access to Shodan -- the world's search engine for internet-connected devices. Built by Vorota AI.

20 tools for passive reconnaissance, vulnerability intelligence, DNS analysis, and device search -- all from your IDE. No packets sent to any target.

---

Quick Start

docker build -t shodan-mcp https://github.com/vorotaai/shodan-mcp.git

Add to your MCP client (Claude Desktop, Cursor, VS Code, etc.):

{
  "mcpServers": {
    "shodan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

4 tools work immediately with no API key -- CVE lookup, CVE search, CPE search, and InternetDB. Get a Shodan API key at account.shodan.io to unlock all 20 tools.

---

Available Tools

Free Tools (No API Key Required)

Tool	Description
shodan-cve-lookup	Look up any CVE -- CVSS v3 scores, EPSS exploit prediction, references, affected CPEs
shodan-search-cves	Search CVEs with filters -- CISA KEV catalog, EPSS sorting, date ranges
shodan-search-cpes	Search CPE identifiers by product name (e.g., "apache", "nginx")
shodan-internetdb-lookup	Fast free IP intelligence -- open ports, vulns, hostnames, CPEs, tags

Reconnaissance Tools (API Key Required)

Tool	Description
shodan-ip-lookup	Full IP reconnaissance -- ports, services, banners, geolocation, vulns, ISP/org, ASN
shodan-search	Search Shodan's database of billions of devices with powerful query syntax
shodan-search-count	Count search results without consuming query credits
shodan-dns-resolve	Resolve hostnames to IP addresses
shodan-dns-reverse	Reverse DNS lookup for IP addresses
shodan-domain-info	Domain reconnaissance -- subdomains, DNS records, tags
shodan-honeypot-score	Detect if an IP is a honeypot (0.0 = real, 1.0 = honeypot)

Utility Tools (API Key Required)

Tool	Description
shodan-api-info	Check API key usage -- plan type, remaining credits
shodan-my-ip	Get your external IP address as seen by Shodan
shodan-account-profile	Account membership, credits, display name
shodan-list-facets	List available search facets for query breakdowns
shodan-list-filters	List available search filters
shodan-parse-query	Analyze and debug search queries
shodan-list-ports	List port numbers Shodan crawlers scan
shodan-list-protocols	List protocols for on-demand scanning
shodan-http-headers	Show HTTP headers your client sends

---

Features

• 20 tools covering IP recon, device search, CVE/CPE intelligence, DNS, domain analysis, and honeypot detection
• 4 free tools that work with zero configuration -- no API key, no signup
• Passive reconnaissance -- all queries hit Shodan's pre-indexed database, no packets touch any target
• Structured Pydantic output -- every tool returns typed models, not raw JSON
• Input validation -- IP addresses, domains, CVE IDs, and queries are validated before any API call
• API key protection -- keys are never exposed in error messages or logs
• Docker-first -- single command to build and run
• Works with all MCP clients -- Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline

---

Example Prompts

Once connected, use natural language in your AI client:

• "What's my external IP address?"
• "What are the details of CVE-2021-44228?"
• "Search for CVEs related to Apache HTTP Server sorted by EPSS score"
• "Look up CPE identifiers for nginx"
• "Do a quick InternetDB lookup on my server's IP"
• "What DNS records exist for my company's domain?"
• "Resolve the hostname myapp.example.com to an IP address"
• "What search filters are available in Shodan?"
• "Check my Shodan API plan and remaining query credits"

---

Installation

Docker (recommended)

docker build -t shodan-mcp https://github.com/vorotaai/shodan-mcp.git

Using uv

git clone https://github.com/vorotaai/shodan-mcp.git
cd shodan-mcp
uv sync --all-groups
shodan-mcp

Using pip

git clone https://github.com/vorotaai/shodan-mcp.git
cd shodan-mcp
pip install .
shodan-mcp

---

Usage with MCP Clients

shodan-mcp works with all major MCP clients: Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, and Cline.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "shodan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add shodan-mcp -e SHODAN_API_KEY=your-api-key-here -- docker run --rm -i -e SHODAN_API_KEY shodan-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "shodan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code / VS Code Insiders

Add to .vscode/mcp.json:

{
  "servers": {
    "shodan-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf / Cline

Use the same configuration as Claude Desktop. Refer to your client's documentation for the config file location.

---

Recommended Workflow

1. Free quick scan -- Use shodan-internetdb-lookup for instant IP intelligence (no key needed)
2. Vulnerability research -- Use shodan-cve-lookup and shodan-search-cves to research CVEs (free)
3. Deep reconnaissance -- Use shodan-ip-lookup for full host details (API key)
4. Discover exposed hosts -- Use shodan-search and shodan-search-count to find and quantify targets
5. DNS intelligence -- Use shodan-dns-resolve, shodan-dns-reverse, and shodan-domain-info
6. Filter honeypots -- Use shodan-honeypot-score to identify deceptive hosts

---

Configuration

Variable	Default	Description
SHODAN_API_KEY	(none)	Shodan API key. Required for 16 tools, not needed for 4 free tools. Get one at account.shodan.io.
FASTMCP_LOG_LEVEL	WARNING	Logging level (DEBUG, INFO, WARNING, ERROR)

---

Security

Authorization is required. While Shodan queries are passive, you must still ensure:

• You have explicit authorization to investigate any target
• You comply with all applicable laws and organizational policies
• You use this tool only for legitimate security research, authorized assessments, or defensive operations

Safety Measures

• Input validation -- IPs, domains, CVE IDs, hostnames, and queries are validated before any API call
• Injection prevention -- Forbidden characters (;, |, &, $, `, etc.) are blocked
• No shell execution -- All HTTP requests use httpx with structured parameters
• API key protection -- Keys are passed via environment variables and stripped from error messages
• Passive by design -- No packets are sent to any target

---

FAQ

Do I need a Shodan API key?

Not to get started. 4 tools work immediately with no key: shodan-cve-lookup, shodan-search-cves, shodan-search-cpes, and shodan-internetdb-lookup. A free Shodan API key unlocks the remaining 16 tools -- get one at account.shodan.io.

What MCP clients are supported?

Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline -- any client supporting MCP stdio transport.

Is it safe?

Yes. All queries are passive (no packets to targets), inputs are validated, and API keys are never exposed in error messages.

How is this different from the Shodan website?

shodan-mcp integrates Shodan directly into your AI workflow. Your AI agent queries Shodan, interprets results, correlates findings, and makes recommendations -- all in a single conversation from your IDE.

---

Contributing

git clone https://github.com/vorotaai/shodan-mcp.git
cd shodan-mcp
uv sync --all-groups
uv run pytest

Please open an issue or pull request on GitHub.

---

License

Apache License 2.0 -- Copyright (c) Vorota AI