# Shodan MCP Server

Give MCP clients (Cursor, Claude Desktop, VS Code, Codex, and others) full access to [Shodan](https://www.shodan.io/) — host recon, banner search, DNS, CVEs, on-demand scans, and network alerts.

Independent project. Not affiliated with Shodan.

## What it does

- **47 tools** covering Shodan REST, [InternetDB](https://internetdb.shodan.io/), [CVEDB](https://cvedb.shodan.io/), and the Exploits API
- **Resources** for account credits, search filters/facets, ports, protocols, and alert triggers
- **Prompts** for host recon, exposure search, domain mapping, and CVE triage
- Compact summaries by default so models see ports/products/vulns instead of raw banner dumps
- Credit warnings on searches that spend query credits
- Scan confirmations (`confirm=true`, plus `confirm_large` / `confirm_internet` for wide targets)
- stdio for desktop clients, Streamable HTTP for a shared process
- InternetDB and CVEDB work **without** an API key

Use this only against assets you are authorized to assess. Shodan's [terms of service](https://www.shodan.io/legal/tos) apply to every request.

## Requirements

- Node.js 20 or later
- A Shodan API key from [account.shodan.io](https://account.shodan.io/) for REST/DNS/scans/alerts/exploits

## Install

```bash
git clone https://github.com/k3nn3dy-ai/Shodan-MCP.git
cd Shodan-MCP
npm install
npm run build
```

Copy `.env.example` and export the key (do not commit it):

```bash
export SHODAN_API_KEY=your-key
```

## MCP client config

Point the client at `dist/index.js`. stdio is the default.

### Cursor / Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/Shodan-MCP/dist/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-key"
      }
    }
  }
}
```

### Docker

```bash
docker build -t shodan-mcp .
```

```json
{
  "mcpServers": {
    "shodan": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
      "env": {
        "SHODAN_API_KEY": "your-key"
      }
    }
  }
}
```

### HTTP transport

```bash
node dist/index.js --http --port 48731
```

MCP endpoint: `http://127.0.0.1:48731/mcp`  
Health check: `http://127.0.0.1:48731/health`

Bind stays on localhost unless you pass `--host`. There is no built-in auth on HTTP — do not expose it to the internet.

## Tools

Free without a key:

| Tool | Purpose |
| --- | --- |
| `shodan_internetdb` | Fast IP enrichment (ports, CPEs, tags, CVE ids) |
| `shodan_cve` | CVE details (CVSS, EPSS, KEV, CPEs) |
| `shodan_cves` | Search CVEs by product or CPE 2.3 |
| `shodan_cpes` | CPE dictionary lookup |

REST (API key):

| Tool | Purpose | Credits |
| --- | --- | --- |
| `shodan_host` | Host card for an IP | none |
| `shodan_search` | Banner search | 1 if filters or `page > 1` |
| `shodan_count` | Match count + facets | none |
| `shodan_search_tokens` | Parse a query | none |
| `shodan_search_facets` / `shodan_search_filters` | Catalog | none |
| `shodan_dns_domain` | Subdomains + records | none |
| `shodan_dns_resolve` / `shodan_dns_reverse` | Forward / reverse DNS | none |
| `shodan_my_ip` | Egress IP Shodan sees | none |
| `shodan_ports` / `shodan_protocols` / `shodan_services` | Crawler catalogs | none |
| `shodan_honeyscore` | Labs honeypot probability | none |
| `shodan_api_info` / `shodan_profile` / `shodan_org` | Plan, credits, org | none |
| `shodan_scan` | On-demand crawl of IPs/CIDRs | 1 scan credit per IP |
| `shodan_scan_status` / `shodan_scans` | Scan progress | none |
| `shodan_scan_internet` | Enterprise Internet-wide scan | scan credits |
| `shodan_alert_*` | Network alerts and triggers | plan-dependent |
| `shodan_notifier_*` | Notifier CRUD | plan-dependent |
| `shodan_query_*` | Community saved-query directory | none |
| `shodan_datasets` / `shodan_dataset_files` | Bulk data listings | plan-dependent |
| `shodan_exploits` / `shodan_exploit_count` | Exploit archive | none |

Host and search tools return a compact summary unless you set `summary=false`. Scans require `confirm=true`. CIDRs wider than `/24` also need `confirm_large=true`.

## Prompts

- `recon_host` — InternetDB → host lookup → CVE triage for one IP
- `search_exposure` — tokenize, count/facet, then one search page
- `domain_osint` — domain DNS then enrich resolved IPs
- `vuln_triage` — CVEDB + exploits + optional exposure count

## Development

```bash
npm test
npm run typecheck
npm run dev          # stdio
npm run dev:http     # http://127.0.0.1:48731
```

Tests mock the Shodan HTTP APIs. They do not spend credits.

## Configuration

| Variable | Default | Meaning |
| --- | --- | --- |
| `SHODAN_API_KEY` | unset | REST / exploits key |
| `SHODAN_BASE_URL` | `https://api.shodan.io` | REST origin |
| `SHODAN_TIMEOUT_MS` | `30000` | Per-request timeout |
| `SHODAN_MAX_RESPONSE_BYTES` | `524288` | Truncate oversized JSON |

API keys are query parameters on Shodan's side. This server never prints them: errors redact `key=...`.

## License

MIT