# Shodan MCP Server

An MCP (Model Context Protocol) server that exposes the [Shodan](https://www.shodan.io/) API as MCP tools. Built with [FastMCP](https://github.com/jlowin/fastmcp) and the official [shodan-python](https://github.com/achillean/shodan-python) library.

## Setup

```sh
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

```sh
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](AGENTS.md) for conventions, architecture, and tool registration patterns used in this project.