Shodan

Provides Claude access to Shodan for IP lookups, searches, counts, and account info via an MCP server.

python

1

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "bonetrees-shodan_mcp": {
      "command": "/full/path/to/poetry",
      "args": [
        "run",
        "-C",
        "/path/to/your/shodan_mcp/pyproject.toml",
        "python",
        "-m",
        "shodan_mcp"
      ],
      "env": {
        "SHODAN_MCP_LOG_LEVEL": "INFO",
        "SHODAN_MCP_PROTOCOL_LOG_LEVEL": "INFO"
      }
    }
  }
}

This MCP server lets Claude access Shodan data for IP lookups, filtered searches, and API usage insights. It enables you to perform host lookups, run targeted Shodan queries, count results without fetching data, and check your Shodan account information directly from your Claude interface.

How to use

Connect the MCP server to Claude using the provided configuration, then issue natural language requests to Claude. You can ask for: - IP lookups to retrieve detailed information about a specific IPv4 address - Searches using Shodan filters like apache port:80 or country:US - Result counts for a given query without returning the full data - Your Shodan account information, including credits and plan details.

How to install

Prerequisites you need before starting: - Python 3.x - Poetry for dependency management - Access to a Shodan API key to enable lookups and searches.

Step by step to get everything running locally: 1. Clone the MCP server project 2. Install dependencies with Poetry 3. Configure your Shodan API key 4. Run the server.

git clone https://github.com/bonetrees/shodan_mcp.git
cd shodan_mcp
poetry install
cp .env.example .env
# Edit .env and add your Shodan API key
.
poetry run python -m shodan_mcp

Configuration and running the server

To connect Claude to this MCP server, configure Claude with the following MCP entry. The runtime uses Poetry to execute the server, and the command line includes the necessary arguments to locate the project and start the MCP module.

{
  "mcpServers": {
    "shodan": {
      "command": "poetry",
      "args": ["run","-C","/path/to/your/shodan_mcp/pyproject.toml","python","-m","shodan_mcp"],
      "cwd": "/path/to/your/shodan_mcp"
    }
  }
}

Environment and logging

Control logging behavior by setting environment variables in your environment or in an .env file. The server supports two logging levels you can adjust to match your needs.

# 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

Security and best practices

Keep your Shodan API key secret and rotate it if you believe it may be compromised. Run the MCP server in a secure environment, and limit Claude’s access to only the data you need for your workflows. Monitor logs for unusual activity and apply updates when new versions are released.

Troubleshooting and tips

If Claude cannot connect, verify that the MCP server is running and that Claude is pointed to the correct command and path. Ensure the environment variables for logging are set correctly and that your Shodan API key is valid.

Available tools

shodan_host_lookup

Look up detailed information about a specific IPv4 address, with optional historical data and minified output.

shodan_search

Query Shodan's database using a flexible query string and limit the number of results returned.

shodan_count

Retrieve the total number of results for a given query without returning the data.

shodan_info

Fetch information about your Shodan API account, including credits and plan details.