shodan

The Shodan MCP Server provides AI agents with access to Shodan's internet-facing device intelligence directly from your MCP client. It exposes a suite of 20 tools for passive reconnaissance, vulnerability intelligence, DNS analysis, and device search. Four free tools work without an API key (CVE lookup, CVE search, CPE search, InternetDB), while the remaining tools require a Shodan API key. You can connect the server to Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, or Cline using the docker-based deployment. Once connected, you can perform targeted lookups, IP intelligence, domain reconnaissance, and advanced searches through natural language prompts or structured tool invocations. The server returns typed, validated outputs to ensure reliable results without exposing raw API keys in logs or errors.

To use, add the server to your MCP client configuration (for example via Claude Desktop, Cursor, or VS Code) by specifying the docker-based command to run the shodan-mcp image and providing your SHODAN_API_KEY in the environment. When you issue queries, you can invoke tools such as shodan-internetdb-lookup for quick IP intelligence, shodan-cve-lookup and shodan-search-cves for vulnerability research, shodan-ip-lookup for full host details, and shodan-dns-resolve or shodan-domain-info for DNS intelligence. The tooling is designed to minimize API-key exposure while enabling rich information retrieval from Shodan’s database.

Prerequisites

• Docker installed on the host (recommended).
• Optional: Python 3.10+ if you prefer building or running locally outside Docker.

Installation (Docker - recommended)

1. Build and run the MCP server image: docker build -t shodan-mcp https://github.com/vorotaai/shodan-mcp.git
2. Run the server via MCP client configuration (example for 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" } } } }

Alternative installation methods (non-Docker)

• UV (Python/uv): git clone https://github.com/vorotaai/shodan-mcp.git cd shodan-mcp uv sync --all-groups shodan-mcp
• Using pip (Python): git clone https://github.com/vorotaai/shodan-mcp.git cd shodan-mcp pip install . shodan-mcp

Prerequisites summary

• Docker (recommended) or Python environment for uv/pip installations
• Shodan API key for full tool access (optional for the free tools)

Tips and common issues:

• SHODAN_API_KEY is required for the majority of tools; four free tools work without it. Ensure you provide a valid key to unlock the rest.
• When using Docker, ensure you pass the API key securely via environment variables in your MCP client configuration.
• If you encounter connection or authentication errors, verify that the API key has the appropriate permissions and that you’re not exceeding rate limits.
• The server emphasizes passive reconnaissance; no packets are sent to targets, aligning with Shodan’s indexed data access.
• For best results, keep your MCP client and the shodan-mcp container updated to the latest version to benefit from tool additions and security fixes.
• Logs should avoid printing sensitive data; consult the client configuration for proper error handling and masking.