bonetrees/shodan_mcp

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

1. Clone the repository:

   git clone https://github.com/bonetrees/shodan_mcp.git
   cd shodan_mcp
   

2. Install dependencies using Poetry:

   poetry install
   

3. 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 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.