Shodan MCP Server

An MCP (Model Context Protocol) server that exposes the Shodan API as MCP tools. Built with FastMCP and the official shodan-python library.

Setup

cp .env.example .env   # add your SHODAN_API_KEY
pip install -r requirements.txt
python server.py

Tools

30 tools across 9 categories:

Core Search

Tool	Description
shodan_search	Search Shodan hosts (query, page, limit, offset, facets, fields)
shodan_host	Get all info on an IP address
shodan_count	Get result count for a query
shodan_search_filters	List available search filters
shodan_search_tokens	Parse and analyze a search query
shodan_search_facets	List available search facets
shodan_ports	List ports Shodan crawls
shodan_protocols	List on-demand scan protocols
shodan_services	List service name to port mappings
shodan_api_info	Get API key info and credits

DNS

Tool	Description
shodan_domain_info	Get DNS records for a domain

IP Tools

Tool	Description
shodan_my_ip	Get your current public IP
shodan_honeyscore	Honeypot probability (0.0–1.0)

Community Queries

Tool	Description
shodan_queries	List shared community queries
shodan_queries_search	Search community queries
shodan_queries_tags	List query tags

Scanning

Tool	Description
shodan_scan	Submit IPs/netblocks for scanning
shodan_scan_status	Check scan status
shodan_scans	List previous scans
shodan_scan_internet	Scan the internet for a port/protocol

Alerts / Monitoring

Tool	Description
shodan_create_alert	Create a network alert
shodan_list_alerts	List or get alert details
shodan_delete_alert	Delete an alert
shodan_alert_triggers	List available alert triggers

Exploits

Tool	Description
shodan_exploit_search	Search the exploit archive
shodan_exploit_count	Count exploit results

Bulk Data

Tool	Description
shodan_datasets	List available datasets
shodan_dataset_files	List files in a dataset

Notifiers

Tool	Description
shodan_notifiers	List configured notifiers
shodan_notifier_providers	List supported providers

Error Handling

All tools catch shodan.APIError and return {"error": "<message>"} instead of raising.

Docker

docker compose up -d --build

Project Structure

├── server.py          # Entry point — creates FastMCP app, wires up tools
├── tools/
│   └── shodan.py      # All 30 tool implementations + Shodan client wrapper
├── AGENTS.md          # Context for AI coding assistants
├── requirements.txt
├── .env.example
├── Dockerfile
└── docker-compose.yml

Agent Context

See AGENTS.md for conventions, architecture, and tool registration patterns used in this project.