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.