Shodan MCP Server

An unofficial MCP (Model Context Protocol) server that provides Claude with access to Shodan for IP address lookups, service discovery, and vulnerability scanning.

Features

Host Lookup: Get detailed information about any IPv4 address
Search: Query Shodan's database using filters (e.g., apache port:80, country:US)
Count: Get result counts for queries without fetching full data
Account Info: Check your Shodan API usage and limits

Installation

Clone the repository:
git clone https://github.com/bonetrees/shodan_mcp.git cd shodan_mcp
Install dependencies using Poetry:
poetry install
Set up your Shodan API key:
cp .env.example .env # Edit .env and add your Shodan API key
Get your API key from Shodan Account.

Usage

Running the Server

poetry run python -m shodan_mcp

Connecting to Claude

Add this configuration to your Claude Desktop config.json file:

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shodan": {
      "command": "/full/path/to/poetry", # you can find this using command `which poetry`
      "args": ["run","-C","/path/to/your/shodan_mcp/pyproject.toml","python", "-m", "shodan_mcp"],
      "cwd": "/path/to/your/shodan_mcp"
    }
  }
}

Replace /path/to/your/shodan_mcp with the actual path to this project.

Available Tools

1. `shodan_host_lookup`

Look up detailed information about a specific IP address.

Parameters:

ip (required): IPv4 address to look up
history (optional): Include historical data (default: false)
minify (optional): Return minimal data (default: false)

Example:

Look up information for IP 8.8.8.8

2. `shodan_search`

Search Shodan's database using query filters.

Parameters:

query (required): Shodan search query
limit (optional): Maximum results to return (1-100, default: 10)

Example queries:

apache port:80 - Apache servers on port 80
country:US ssl:true - SSL servers in the US
product:nginx - Nginx servers
port:22 - SSH servers

3. `shodan_count`

Get the total count of results for a query without fetching the actual data.

Parameters:

query (required): Shodan search query

4. `shodan_info`

Get information about your Shodan API account (credits, plan, etc.).

Parameters: None

Example Usage with Claude

Once connected, you can ask Claude things like:

"Look up the IP address 1.1.1.1 using Shodan"
"Search for Apache servers in the US"
"How many SSH servers are there globally?"
"What's my current Shodan API usage?"

Logging

The server provides comprehensive logging at multiple levels:

MCP Protocol Logging

Log messages are sent to the connected MCP client (like Claude Desktop) and appear in the client's interface. This includes:

Debug: Detailed execution information
Info: General operational messages
Warning: Important notices (e.g., sensitive searches)
Error: Error conditions and failures

Server-side Logging

Traditional Python logging for debugging and monitoring. Logs are written to the console.

Configuration

Control logging levels via environment variables:

# Python logging level (DEBUG, INFO, WARNING, ERROR)
SHODAN_MCP_LOG_LEVEL=INFO

# MCP protocol logging level (what gets sent to Claude)
SHODAN_MCP_PROTOCOL_LOG_LEVEL=INFO

Add these to your .env file to customize logging behavior.

Development

Project Structure

shodan_mcp/
├── src/
│   └── shodan_mcp/
│       ├── __init__.py
│       ├── server.py
│       └── logging_config.py
├── .env.example
├── pyproject.toml
└── README.md

Dependencies

mcp - Model Context Protocol library
shodan - Official Shodan Python library
python-decouple - Environment variable management

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is an unofficial tool. Please respect Shodan's terms of service and rate limits.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides Claude with access to Shodan for IP address lookups, service discovery, and vulnerability scanning, allowing users to query information about hosts, count results, and check API usage.

Related MCP Servers

mcp-shodan
BurtTheCoder
-
security
A
license
-
quality
MCP server for querying the Shodan API and Shodan CVEDB. This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more.
Last updated -
7
658
65
JavaScript
MIT License
ADEO CTI MCP Server
ADEOSec
-
security
F
license
-
quality
A Model Context Protocol server that provides access to Shodan and VirusTotal APIs for cybersecurity analysis, enabling analysts to perform network intelligence operations including host lookups, vulnerability analysis, and threat intelligence gathering.
Last updated -
13
TypeScript
Shodan MCP Server
Cyreslab-AI
A
security
A
license
A
quality
Provides access to Shodan API functionality, enabling AI assistants to query information about internet-connected devices for cybersecurity research and threat intelligence.
Last updated -
23
25
JavaScript
MIT License
Shodan MCP Server
X3r0K
-
security
F
license
-
quality
A WebSocket server that provides MCP interface for searching and retrieving information about internet-connected devices, IP addresses, DNS data, and CVE vulnerabilities through the Shodan API.
Last updated -
1
JavaScript

View all related MCP servers

Shodan MCP Server