Shodan

A simple MCP for SHODAN. It allows query by IP, Domain and some custom Query. [Requires Shodan API Token]

python

3

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "irootsec-shodan-mcp": {
      "command": "/path/to/run_shodan_mcp.sh",
      "args": [],
      "env": {
        "SHODAN_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

This MCP server lets you query Shodan directly from MCP-compatible clients, enabling domain, IP, and DSL-style searches to discover exposed devices and services. It simplifies integrating Shodan-powered insights into your applications and automations without leaving your MCP environment.

How to use

You will run the Shodan MCP server locally and connect to it from your MCP client. Use the available tools to perform domain searches, IP lookups, and advanced queries. The server awaits MCP connections and returns structured results based on Shodan data.

Typical workflows include: searching for hosts by domain to map infrastructure, looking up a specific public IP to retrieve organization and service details, and running complex DSL queries to filter results by port, OS, or service type.

How to install

# Prerequisites: Python 3.8+, virtualenv

# 1) Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2) Install dependencies
pip install -r requirements.txt

# 3) Prepare the run script that launches the MCP server
# This script should invoke the Python-based MCP server (shodan_mcp.py)
# The script path will be referenced by the MCP configuration
```} ,{

Create the Shodan API key file used by the server. Put your key in a .env file as SHODAN_KEY. You can obtain a free key from shodan.io.

echo 'SHODAN_KEY=YOUR_KEY_HERE' > .env

Configuration and starting the server

Configure the MCP client to point to a local server that executes the launch script. In the MCP client settings, set a new MCP server with the start command that runs the script you prepared.

{
  "mcpServers": {
    "shodan": {
      "command": "/path/to/run_shodan_mcp.sh"
    }
  }
}

Verification

Verify the server starts without errors by executing the launch script manually and ensuring it stays running, waiting for MCP connections.

./path/to/run_shodan_mcp.sh

Available tools

shodan_search_domain

Search hosts whose hostname matches a given domain; supports optional page parameter for pagination.

shodan_lookup_ip

Retrieve data for a specific public IP, including organization, location, and services.

shodan_search_query

Execute a Shodan DSL query with advanced filters to refine results by domain, IP, port, OS, and more.