MCP HubMCP Hub
BurtTheCoder

mcp-shodan

by: BurtTheCoder

MCP server for querying the Shodan API

25created 12/12/2024
Visit
Shodan
API

📌Overview

Purpose: To provide an MCP server for efficient querying of the Shodan API and CVEDB, enabling enhanced access to network intelligence and security services.

Overview: The Shodan MCP Server allows users to conduct a variety of information-gathering tasks such as IP reconnaissance, DNS lookups, vulnerability assessments, and device discovery. By integrating with Shodan, it simplifies the process of obtaining and analyzing data about internet-connected devices and their vulnerabilities, yielding structured outputs suitable for further analysis.

Key Features:

  • Network Reconnaissance: Enables extensive querying of IP addresses for open ports, services, and vulnerabilities, improving threat assessment capabilities.

  • DNS Operations: Facilitates both forward and reverse DNS lookup functionalities, enhancing domain and IP address analysis.

  • Vulnerability Intelligence: Provides access to Shodan's comprehensive CVEDB for detailed information on vulnerabilities, enabling users to track and mitigate security risks effectively.

  • Device Discovery: Offers advanced search functionalities to explore Shodan's database of internet-connected devices, streamlining the process of device identification.

Shodan MCP Server

A Model Context Protocol (MCP) server for querying the Shodan API and Shodan CVEDB. This server provides access to Shodan's network intelligence and security services, including IP reconnaissance, DNS operations, vulnerability tracking, and device discovery. All tools provide structured, formatted output for easy analysis and integration.

Quick Start (Recommended)

Installing via Smithery

To install Shodan Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude

Installing Manually

  1. Install the server globally via npm:
npm install -g @burtthecoder/mcp-shodan
  1. Add to your Claude Desktop configuration file:
{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Configuration file location:

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

Alternative Setup (From Source)

  1. Clone and build:
git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run build
  1. Add to your Claude Desktop configuration:
{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Features

  • Network Reconnaissance: Query detailed information about IP addresses, including open ports, services, and vulnerabilities
  • DNS Operations: Forward and reverse DNS lookups
  • Vulnerability Intelligence: Access to Shodan's CVEDB for vulnerability info, CPE lookups, and CVE tracking
  • Device Discovery: Search Shodan's database of internet-connected devices with advanced filtering

Tools

1. IP Lookup Tool

  • Name: ip_lookup
  • Description: Retrieve information about an IP address, including geolocation, open ports, services, SSL certificates, hostnames, and cloud provider details
  • Parameters:
    • ip (required): IP address to lookup
  • Returns:
    • IP info (address, organization, ISP, ASN)
    • Location (country, city, coordinates)
    • Services (ports, protocols, banners)
    • Cloud provider details (if available)
    • Associated hostnames and domains
    • Tags

2. Shodan Search Tool

  • Name: shodan_search
  • Description: Search Shodan's database of internet-connected devices
  • Parameters:
    • query (required): Shodan search query
    • max_results (optional, default: 10): Number of results to return
  • Returns:
    • Search summary with total results
    • Country-based distribution stats
    • Detailed device info including IP, org, ISP, location, services, web server info, hostnames, and domains

3. CVE Lookup Tool

  • Name: cve_lookup
  • Description: Query detailed vulnerability information from Shodan's CVEDB
  • Parameters:
    • cve (required): CVE identifier (e.g., CVE-2021-44228)
  • Returns:
    • Basic info (ID, published date, summary)
    • Severity scores (CVSS v2 & v3, EPSS)
    • Impact assessment (KEV status, mitigations, ransomware associations)
    • Affected products (CPEs)
    • References

4. DNS Lookup Tool

  • Name: dns_lookup
  • Description: Resolve domain names to IP addresses
  • Parameters:
    • hostnames (required): Array of hostnames
  • Returns:
    • DNS resolutions mapping hostnames to IPs
    • Summary of lookups and queried hostnames

5. Reverse DNS Lookup Tool

  • Name: reverse_dns_lookup
  • Description: Perform reverse DNS lookups to find hostnames for IP addresses
  • Parameters:
    • ips (required): Array of IP addresses
  • Returns:
    • Reverse DNS resolutions mapping IPs to hostnames
    • Summary of lookups and results

6. CPE Lookup Tool

  • Name: cpe_lookup
  • Description: Search for Common Platform Enumeration (CPE) entries by product name
  • Parameters:
    • product (required): Product name
    • count (optional, default: false): Return count of matches if true
    • skip (optional, default: 0): Number of CPEs to skip
    • limit (optional, default: 1000): Max number of CPEs to return
  • Returns:
    • Count of matching CPEs if count is true
    • List of CPEs with pagination details if count is false

7. CVEs by Product Tool

  • Name: cves_by_product
  • Description: Search vulnerabilities affecting specific products or CPEs
  • Parameters:
    • cpe23 (optional): CPE 2.3 identifier
    • product (optional): Product name
    • count (optional, default: false): Return count only if true
    • is_kev (optional, default: false): Return CVEs with KEV flag only if true
    • sort_by_epss (optional, default: false): Sort by EPSS score if true
    • skip (optional, default: 0): Number of CVEs to skip
    • limit (optional, default: 1000): Max number of CVEs to return
    • start_date (optional): Start date for filtering (YYYY-MM-DDTHH:MM:SS)
    • end_date (optional): End date for filtering (YYYY-MM-DDTHH:MM:SS)
  • Notes:
    • Provide either cpe23 or product, but not both
    • Date filtering uses published time
  • Returns:
    • Query info
    • Results summary with pagination
    • Detailed vulnerability info (basic info, severity, impact, references)

Requirements

Troubleshooting

API Key Issues

If you see API key errors (e.g., "Request failed with status code 401"):

  1. Verify your API key:

    • Valid Shodan API key from your account
    • Sufficient credits/permissions
    • No extra spaces or quotes
    • Set properly in SHODAN_API_KEY environment variable

  2. Common error codes:

    • 401 Unauthorized: Invalid API key or missing auth
    • 402 Payment Required: Out of query credits
    • 429 Too Many Requests: Rate limit exceeded

  3. Configuration steps:
    a. Obtain API key from Shodan Account
    b. Add to config file:

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

    c. Save config and restart Claude Desktop

  4. Testing your key:

    • Try a simple query, e.g., dns_lookup for "google.com"
    • Check Shodan account dashboard for credits
    • Test with curl:
    curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"

Module Loading Issues

  • For global installation: Use simple configuration in Quick Start
  • For source install: Ensure Node.js v18 or later

Development

Run in development mode with hot reloading:

npm run dev

Error Handling

The server handles errors including:

  • Invalid API keys
  • Rate limiting
  • Network errors
  • Invalid input parameters
  • Invalid CVE formats
  • Invalid CPE lookup parameters
  • Invalid date formats
  • Mutually exclusive parameter validation

Version History

  • v1.0.12: Added reverse DNS lookup and improved output formatting
  • v1.0.7: Added CVEs by Product search and renamed vulnerabilities tool to cve_lookup
  • v1.0.6: Added CVEDB integration for CVE lookups and CPE search
  • v1.0.0: Initial release with core functionality

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.