shodan-mcp

A minimal Model Context Protocol server for Shodan. 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

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

Register it with Claude Code:

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):

SHODAN_API_KEY=your-key-here node index.js

A Shodan API key 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.

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

Related MCP server: Shodan MCP Server

Tools

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