mcp-shodan

The mcp-shodan server exposes a set of tools that integrate Shodan’s network intelligence into your MCP workflow. It provides access to Shodan’s IP reconnaissance, DNS operations, vulnerability data from the CVEDB, and device discovery capabilities. You can query detailed information about IP addresses, perform forward and reverse DNS lookups, search Shodan’s device database, and retrieve CVE information tied to products or CPEs. Each tool returns structured, machine-friendly output designed for easy consumption by other MCP components or automation scripts.

Once the server is running, you can invoke the built-in tools through your MCP client by naming the tool (for example ip_lookup, shodan_search, cve_lookup, dns_lookup, reverse_dns_lookup, cpe_lookup, cves_by_product) and passing the required parameters. Ensure you provide your Shodan API key via the SHODAN_API_KEY environment variable when configuring the server, so requests to Shodan are authenticated and rate-limited appropriately.

Prerequisites:

• Node.js (v20 or later) and npm
• A valid Shodan API Key

Manually install via npm and configure the server:

1. Install the MCP server globally:

npm install -g @burtthecoder/mcp-shodan

2. Configure Claude Desktop (example) to use the installed server:

{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Configuration file locations (examples):

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

3. Alternatively, run from source:

git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run build

4. If using the built artifact, configure Claude Desktop to point to the built index:

{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

5. Start or reload Claude/Desktop to apply changes.

Tips and common issues:

• Ensure SHODAN_API_KEY is set and valid; invalid keys will generate authentication errors (401/403).
• If you encounter rate-limit errors, check your Shodan credits and adjust usage or apply for higher quota.
• The mcp_config example assumes the MCP server is invoked via npx. If deploying differently, adapt the command and args accordingly (e.g., node with a built index.js).
• When running from source, run npm run build to generate the production index.js used by the node command.
• Keep the API key secure and do not commit it to version control; use environment variables in your deployment configuration.