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)

Reconnaissance Tools (API Key Required)

Utility Tools (API Key Required)

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

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