# shodan-mcp

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server for
[Shodan](https://www.shodan.io). It exposes only the endpoints needed for two
things: checking what your own infrastructure exposes to the internet, and
searching Shodan's data for general reconnaissance. One file, no extra
dependencies beyond the official MCP SDK.

## Quick start

```bash
git clone https://github.com/aethrox/shodan-mcp.git
cd shodan-mcp
npm install
```

Register it with Claude Code:

```bash
claude mcp add shodan -s user -e SHODAN_API_KEY=your-key-here -- node /absolute/path/to/index.js
```

Or run it standalone (it speaks MCP over stdio):

```bash
SHODAN_API_KEY=your-key-here node index.js
```

A [Shodan API key](https://account.shodan.io/) is required either way. Instead
of exporting `SHODAN_API_KEY` yourself, you can copy `.env.example` to `.env`
and put the key there; the server loads it automatically on startup. `.env`
is gitignored, so it never gets committed.

```bash
cp .env.example .env
# then edit .env and set SHODAN_API_KEY
```

## Tools

| Tool | What it does |
|---|---|
| `shodan_my_ip` | Public IP Shodan sees this API key's requests coming from. Starting point for scanning your own infrastructure. |
| `shodan_host_lookup` | Full Shodan record for one IP: open ports, banners, detected products/versions, known vulnerabilities. |
| `shodan_search` | Search Shodan's device database using [Shodan search syntax](https://www.shodan.io/search/filters) (`country:`, `net:`, `vuln:`, ...). |
| `shodan_cve_lookup` | CVE details from Shodan's CVEDB: CVSS score, affected CPEs, how many exposed hosts Shodan currently sees. |
| `shodan_cves_by_product` | CVEs affecting a given CPE (product + version). |
| `shodan_host_count` | Count hosts matching a search query without spending query credits. |
| `shodan_search_filters` | List the search filters Shodan supports (country, port, net, vuln, ...). |
| `shodan_dns_domain` | Subdomains and DNS entries Shodan has seen for a domain. |
| `shodan_dns_resolve` | Resolve hostnames to IP addresses. |
| `shodan_dns_reverse` | Reverse-resolve IP addresses to hostnames. |
| `shodan_account_info` | This API key's plan and remaining query/scan credits. |

## Requirements

- Node.js 20+
- A Shodan API key with the plan tier needed for the endpoints you use (host
  lookup and search require more than the free tier)

## Limitations

- No caching or rate-limit handling: requests go straight to the Shodan API,
  so hitting your plan's rate limit surfaces as a raw API error.
- No pagination helper for `shodan_search`; multi-page results need repeated
  calls with the `page` argument.
- The API key is passed as a plain environment variable to the MCP process,
  same as any other stdio MCP server. Don't commit it, and be mindful of
  where your MCP client config file (e.g. `claude mcp add` output) ends up
  stored.

## License

MIT