SHODAN

SHODAN-MCP provides a focused, high-performance interface to the Shodan API, enabling you to search, analyze, and map internet-facing devices from your preferred MCP-enabled tools and assistants. With an asynchronous core and convenient integration options, you can perform security research, host intelligence, and DNS work through a streamlined MCP workflow.

How to use

Interact with SHODAN-MCP through MCP-enabled clients to perform searches, retrieve detailed host data, and analyze vulnerability and DNS information. Start with a basic search to filter results by criteria, then drill into individual hosts to view services, banners, and configurations. Use the domain and DNS commands to explore infrastructure and subdomains, and leverage vulnerability endpoints to investigate CVEs and related exposure.

How to install

Prerequisites: ensure you have Python 3.8 or higher and a Shodan API key. You also need a way to manage dependencies (pip is sufficient for most setups). Install the MCP server locally and set up your API key before running.

# Clone the project
git clone https://github.com/yourusername/shodan-mcp.git
cd shodan-mcp

# Install dependencies
pip install -r requirements.txt

# Set up your Shodan API key in a local environment file
echo "SHODAN_API_KEY=your_api_key_here" > .env

# Run the MCP server using uv (as outlined in the integration steps)
uv --directory /path/to/shodan-mcp/shodan-mcp-server run shodan_mcp.py

Additional sections

Configuration and usage notes are provided to help you integrate SHODAN-MCP with your preferred MCP client. The recommended runtime is uv for fast, reliable management of Python environments and dependencies.

Security and ethics: only perform authorized research on devices you own or have explicit permission to test. Keep your API key secure and do not share it publicly.

Notes on usage: some actions consume Shodan API credits; plan your queries accordingly and consider batching or rate-limiting strategies for large analyses.

Example MCP connection configuration for local startup (stdio-based):

{
  "mcpServers": {
    "shodan": {
      "type": "stdio",
      "name": "shodan",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/shodan-mcp/shodan-mcp-server",
        "run",
        "shodan_mcp.py"
      ]
    }
  }
}

Troubleshooting and tips

If you encounter API key errors, verify that your key is valid and correctly configured in your environment. For rate limits, implement backoff strategies or consider upgrading your Shodan plan. If modules are not found, ensure dependencies are installed successfully.

Available tools

test

Check if the MCP server responds and is reachable from the client.

check_key

Validate the Shodan API key and reveal account information.

search

Query the Shodan database with filters and parameters to discover matching hosts.

count

Return the number of results for a given query without consuming API credits.

get_filters

Retrieve all available Shodan search filters for building queries.

get_facets

Obtain facets for statistical analysis of search results.

host

Fetch detailed information about a specific IP address, including services and banners.

domain_info

Gather DNS information and subdomains for a domain.

dns_lookup

Resolve hostnames to IP addresses.

reverse_dns

Map IP addresses back to hostnames.

cve_info

Get detailed information about a specific CVE.

find_cpes

Find CPE identifiers related to a product.

find_cves

Identify vulnerabilities by product or CPE.