Overview

The Shodan MCP Server provides a lightweight Model Context Protocol (MCP) adapter that exposes Shodan functionality as tools for models and developer workflows. It turns common Shodan API operations (search, host lookup, counts, and facets) into RESTful endpoints and MCP-compliant tool descriptions so LLMs and orchestration layers can discover and call them programmatically.

This server is useful when you want to integrate asset discovery into automated workflows: feed a model up-to-date internet-exposure data, allow tools to enrich alerts with host details, or let security automation query Shodan without embedding the API key into each consumer. It centralizes Shodan access behind a single service, simplifies authentication, and provides consistent JSON responses suitable for model consumption or downstream automation.

Features

Exposes core Shodan API operations as MCP-friendly endpoints
Centralized API key management via environment variables
Simple REST interface for search, host lookup, counts, and facets
Suitable for integration with LLM tool chains and automation pipelines
Docker-friendly for easy deployment and isolation
Minimal dependencies—easy to run locally or in cloud environments

Installation / Configuration

Prerequisites:

Python 3.9+ (or Docker)
A Shodan API key (create one at https://account.shodan.io/)

Clone the repository and install dependencies:

git clone https://github.com/Hexix23/shodan-mcp.git
cd shodan-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create a .env file with your Shodan API key and optional server settings:

SHODAN_API_KEY=your_shodan_api_key_here
HOST=0.0.0.0
PORT=8080
LOG_LEVEL=info

Run locally using uvicorn (FastAPI example):

uvicorn app.main:app --host ${HOST:-0.0.0.0} --port ${PORT:-8080} --reload

Or using Docker:

# Build image
docker build -t shodan-mcp .

# Run container with environment variables
docker run -d --name shodan-mcp -p 8080:8080 \
  -e SHODAN_API_KEY=your_shodan_api_key_here \
  shodan-mcp

The repository README on GitHub contains the most up-to-date instructions and debugging tips: https://github.com/Hexix23/shodan-mcp

Available Resources

The server exposes REST endpoints that correspond to common Shodan operations. Typical endpoints (root paths are illustrative; refer to your deployed server for exact routes):

Tool / Endpoint	Method	Description
/tools/search	POST	Full text search across Shodan with query and pagination
/tools/host	GET	Retrieve host details by IP address
/tools/count	GET	Return counts for a query (useful for quick metrics)
/tools/facets	GET	Query facets (e.g., product, port, country) for a search
/tools/ports	GET	List common ports and counts across Shodan indexed hosts

Example JSON request body for search (POST /tools/search):

{
  "query": "nginx country:US",
  "page": 1,
  "facets": ["product", "port"]
}

Example response fields returned:

matches: array of matching host documents
total: total results
facets: aggregated facet counts

Use Cases

Inventory internet-facing assets
- Periodically run a search for organization-hosted domains or IP ranges (e.g., “org:example.com” or “net:203.0.113.0/24”) to build or refresh an external asset inventory. Use /tools/count to produce quick metrics and /tools/host to enrich specific IPs with banners and open ports.
Monitor exposure of sensitive services
- Automate a scheduled query for databases, default-password services, or exposed management interfaces (e.g., “port:27017 product:MongoDB”). Trigger alerts when counts increase or when new hosts appear.
Incident response enrichment
- During triage, call /tools/host?ip=1.2.3.4 to get service banners, open ports, and historical fingerprints. Feed this context into a playbook or LLM-based assistant to suggest containment or hunting steps.
Compliance and reporting
- Use /tools/count to produce regular reports on how many assets expose insecure protocols (FTP, Telnet) or outdated products, and track changes over time for audits.

Example curl: perform a search and return the first page of results

curl -X POST "http://localhost:8080/tools/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"apache country:US","page":1}'

Example curl: get host details

curl "http://localhost:8080/tools/host?ip=8.8.8.8"

Tips for Developers

Keep your SHODAN_API_KEY secret—only inject it into the MCP server environment, not into client code.
Use count and facets for lightweight checks before fetching heavy host documents.
If integrating with LLMs, expose only the minimal subset of tools the model needs and consider rate limiting and caching to control Shodan usage.
Monitor usage and errors—Shodan API has rate limits and may return throttling responses that your MCP server should handle gracefully.

For full API reference and examples, see the repository on GitHub: https://github.com/Hexix23/shodan-mcp

Shodan MCP Server for Network Asset Discovery