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 keyGet 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 uphistory(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 querylimit(optional): Maximum results to return (1-100, default: 10)
Example queries:
apache port:80- Apache servers on port 80country:US ssl:true- SSL servers in the USproduct:nginx- Nginx serversport: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 libraryshodan- Official Shodan Python librarypython-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.