Shodan MCP Server

# Shodan MCP Server An unofficial MCP (Model Context Protocol) server that provides Claude with access to [Shodan](https://www.shodan.io/) 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 1. **Clone the repository:** ```bash git clone https://github.com/bonetrees/shodan_mcp.git cd shodan_mcp ``` 2. **Install dependencies using Poetry:** ```bash poetry install ``` 3. **Set up your Shodan API key:** ```bash cp .env.example .env # Edit .env and add your Shodan API key ``` Get your API key from [Shodan Account](https://account.shodan.io/). ## Usage ### Running the Server ```bash 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` ```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: ```bash # 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](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.