Home / MCP / Shodan MCP Server

Shodan MCP Server

Provides access to Shodan network intelligence via MCP for IP lookups, DNS, CVEDB CVEs, and device discovery.

javascript

88stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "shodan_http": {
            "url": "https://mcp-shodan.example.com/mcp"
        }
    }
}

You can query Shodan's network intelligence and security data through this MCP server. It lets you perform IP lookups, DNS operations, CVE inquiries from Shodan’s CVEDB, and device discovery, all with structured output that’s easy to analyze and integrate into your workflow.

How to use

You run the Shodan MCP Server as a local process and connect to it from your MCP client. Use the tools to look up IP information, search Shodan’s device database, fetch CVEs, and resolve DNS names. Each tool returns structured results that you can consume directly in your client or automation pipeline.

How to install

Prerequisites you need before installing: Node.js (version 18 or later) and a valid Shodan API key.

Option A: Install via Smithery (recommended for Claude Desktop users)

npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude

Option B: Install Manually (local MCP server)

npm install -g @burtthecoder/mcp-shodan

Manual config and running from source

If you want to run from source or modify the code, clone the project, install dependencies, and build. Then configure Claude Desktop to launch the built index.

git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run build

Configure Claude Desktop to load the server from the built index using the stdio runtime. The example below shows how to point to the built index and provide your Shodan API key.

{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Configuration notes

The server requires your Shodan API key to run. Save the key in the environment under SHODAN_API_KEY for the stdio setup. If you run via Smithery, the CLI handles the necessary environment wiring for Claude Desktop.

Troubleshooting

If you encounter API key errors, verify that your key is valid, has the necessary permissions, is not surrounded by stray quotes or spaces, and is correctly set in the environment variable SHODAN_API_KEY.

Common errors include 401 Unauthorized (invalid key), 402 Payment Required (insufficient credits), and 429 Too Many Requests (rate limit). Ensure you can run a basic query against Shodan with your key to validate access.

Tools overview

The server exposes a suite of tools to access Shodan data. Each tool is designed to return structured information suitable for immediate use in dashboards, automations, or further analysis.

Error handling and resilience

The server includes robust error handling for invalid API keys, rate limits, network errors, and invalid input parameters to help you diagnose and recover from common issues quickly.

Available tools

ip_lookup

Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available.

shodan_search

Search Shodan's database of internet-connected devices and return a summary, distribution by country, and detailed device information.

cve_lookup

Query detailed vulnerability information from Shodan's CVEDB using a CVE identifier.

dns_lookup

Resolve a list of hostnames to IP addresses using Shodan's DNS service.

reverse_dns_lookup

Perform reverse DNS lookups to discover hostnames associated with IP addresses.

cpe_lookup

Search for CPE entries by product name and optionally return count or paginated results.

cves_by_product

Search for CVEs affecting specific products or CPEs with options for filtering and sorting by EPSS or KEV.