Skip to main content
Glama
Sign In
Shodan MCP Server

Shodan MCP Server

by GangGreenTemperTatum
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Shodan MCP Server (stdio)

Model Context Protocol (MCP) server integration for Shodan API, enabling Claude AI to perform comprehensive security reconnaissance, vulnerability assessment, and threat intelligence gathering.

Features

  • Comprehensive Host Search: Search Shodan's database of internet-connected devices

  • Detailed Host Information: Get in-depth data about specific IP addresses

  • DNS Operations: Forward and reverse DNS lookups

  • Vulnerability Discovery: Find hosts with specific CVEs and security issues

  • Exploit Database: Search for available exploits

  • API Management: Monitor query credits and usage

  • Protocol/Port Information: Access Shodan's supported protocols and ports

Related MCP server: mcp-shodan

Prerequisites

  • Node.js 18.0.0 or higher

  • Shodan API key (Get one here)

  • Claude Desktop or compatible MCP client

Installation

1. Clone and Install Dependencies

cd /path/to/shodan-mcp-server
npm install

2. Get Shodan API Key

  1. Sign up at shodan.io

  2. Navigate to Account

  3. Copy your API key

3. Configure Environment

Create a .env file:

echo "SHODAN_API_KEY=your_api_key_here" > .env

4. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/path/to/shodan-mcp-server/src/index.js"],
      "env": {
        "SHODAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

shodan_host_search

Search Shodan for hosts matching a query.

Parameters:

  • query (required): Shodan search query

  • facets (optional): Comma-separated facets for aggregation

  • page (optional): Page number for pagination

Example:

Query: "apache country:US"
Facets: "country,org,port"

shodan_host_info

Get detailed information about a specific IP address.

Parameters:

  • ip (required): IP address to lookup

  • history (optional): Include historical data

Example:

IP: "8.8.8.8"
History: true

shodan_dns_lookup

Resolve domain names to IP addresses.

Parameters:

  • hostnames (required): Array of hostnames

Example:

Hostnames: ["example.com", "google.com"]

shodan_dns_reverse

Perform reverse DNS lookup on IP addresses.

Parameters:

  • ips (required): Array of IP addresses

Example:

IPs: ["8.8.8.8", "1.1.1.1"]

shodan_api_info

Get information about your API plan and remaining credits.

Parameters: None

shodan_exploits_search

Search the Shodan Exploits database.

Parameters:

  • query (required): Search query

  • facets (optional): Facets for aggregation

  • page (optional): Page number

Example:

Query: "CVE-2021-44228"
Facets: "type,platform"

shodan_ports

Get list of ports that Shodan crawls.

Parameters: None

shodan_protocols

Get supported protocols for querying.

Parameters: None

shodan_count

Get total count of results for a query without returning data.

Parameters:

  • query (required): Shodan search query

  • facets (optional): Facets for aggregated counts

shodan_query_search

Search for saved community queries.

Parameters:

  • query (required): Search term

  • page (optional): Page number

shodan_query_tags

Get popular tags for saved queries.

Parameters:

  • size (optional): Number of tags to return (default: 10)

Shodan Query Syntax

Basic Filters

city:"San Francisco"          - Filter by city
country:US                    - Filter by country code
org:"Google"                  - Filter by organization
net:192.168.0.0/24           - Filter by IP range
port:22                       - Filter by port
product:Apache               - Filter by product name
version:2.4.1                - Filter by version
os:"Windows 10"              - Filter by operating system

Vulnerability Filters

vuln:CVE-2021-44228          - Search for specific CVE
vuln:CVE-2020-*              - Search for CVEs from 2020

HTTP Filters

http.title:"Admin Panel"      - Filter by page title
http.html:"password"          - Search in HTML content
http.status:200               - Filter by HTTP status
http.component:"wordpress"    - Filter by web component

SSL Filters

ssl:"example.com"             - Search by SSL certificate
ssl.cert.expired:true         - Find expired certificates
ssl.version:sslv2            - Filter by SSL version
ssl.cipher:export            - Find weak ciphers

Combining Filters

port:22 country:US org:"Amazon"
apache city:"Los Angeles" vuln:CVE-2021-44228

Usage Examples

1. Asset Discovery

// Find all assets for an organization
{
  "query": "org:\"Example Corp\"",
  "facets": "country,port,product"
}

2. Vulnerability Assessment

// Find systems vulnerable to Log4Shell
{
  "query": "vuln:CVE-2021-44228 country:US",
  "page": 1
}

3. Threat Intelligence

// Find potential C2 infrastructure
{
  "query": "product:\"Cobalt Strike\"",
  "facets": "country,org"
}

4. DNS Investigation

// Resolve multiple domains
{
  "hostnames": [
    "example.com",
    "suspicious-domain.com"
  ]
}

5. Exploit Research

// Find exploits for a CVE
{
  "query": "CVE-2021-44228",
  "facets": "type,platform,author"
}

Skills

Three comprehensive skills are included:

1. shodan-recon

Perform reconnaissance and asset discovery. Automates the process of:

  • DNS enumeration

  • Asset discovery

  • Port and service enumeration

  • Detailed host analysis

  • Comprehensive reporting

2. shodan-vuln-scan

Identify and assess vulnerabilities. Includes:

  • CVE discovery

  • Exploit availability checking

  • Risk assessment

  • Remediation recommendations

  • Vulnerability matrix generation

3. shodan-threat-intel

Gather threat intelligence. Capabilities:

  • C2 infrastructure tracking

  • Phishing infrastructure identification

  • Malware distribution point discovery

  • IOC enrichment

  • Threat actor tracking

  • Temporal analysis

Development

Running in Development

npm run dev

Testing Tools

# Test the server manually
node src/index.js

# In another terminal, send test requests
# (requires MCP client for full testing)

Adding New Tools

  1. Add tool definition to TOOLS array in src/index.js

  2. Add case handler in CallToolRequestSchema handler

  3. Update README with new tool documentation

Resources

Available Tools

11 tools
shodan_api_infoB

Get information about the current API plan including query credits remaining and scan credits.

Inputs: no named parameters.

shodan_countA

Get the total number of results for a search query without returning the actual results. Useful for scoping searches before running full queries to avoid wasting API credits.

Best Practice: Always use count first for large ICS/SCADA queries.

Example Workflow:

  1. Count: "port:502 tag:ics" → 50,000 results

  2. Narrow: "port:502 tag:ics country:US" → 15,000 results

  3. Refine: "port:502 tag:ics country:US org:"Electric"" → 500 results

  4. Then run full search on refined query

Use with facets to see distribution without burning credits on full results.

Inputs: query (required), facets.

shodan_dns_lookupC

Perform DNS lookups to resolve domain names to IP addresses.

Inputs: hostnames (required).

shodan_dns_reverseB

Reverse DNS lookup to find hostnames associated with IP addresses.

Inputs: ips (required).

shodan_exploits_searchB

Search for exploits in the Shodan Exploits database. Useful for finding known exploits for specific CVEs or software. Critical for ICS/SCADA security assessments.

ICS/SCADA Exploit Examples:

  • "Modbus" - Modbus protocol exploits

  • "SCADA" - General SCADA vulnerabilities

  • "Siemens" - Siemens PLC/SCADA exploits

  • "Schneider Electric" - Schneider vulnerabilities

  • "Allen-Bradley" - Rockwell exploits

  • "CVE-2019-6575" - Modbus simulator vulnerability

  • "CVE-2020-15782" - BACnet buffer overflow

  • "type:remote platform:hardware" - Hardware-specific

  • "ICS" - Industrial Control System exploits

Common ICS CVE Searches:

  • Modbus vulnerabilities: Often memory corruption, authentication bypass

  • SCADA exploits: Remote code execution, denial of service

  • PLC exploits: Ladder logic manipulation, configuration changes

Inputs: query (required), facets, page.

shodan_host_infoB

Get detailed information about a specific host by IP address. Returns all services, open ports, vulnerabilities, and historical data.

Inputs: ip (required), history.

shodan_host_searchA

Search Shodan for hosts matching a query. Returns detailed information about discovered hosts including IP addresses, ports, services, and vulnerabilities. Use for asset discovery and reconnaissance.

ICS/SCADA Examples:

  • "port:502 tag:ics" - Modbus industrial control systems

  • "port:502 Siemens" - Siemens SCADA/PLCs

  • "port:502 "Schneider Electric"" - Schneider Modbus devices

  • "port:44818 "Allen-Bradley"" - Rockwell EtherNet/IP

  • "port:20000 tag:ics" - DNP3 utility SCADA

  • "port:102 S7" - Siemens S7 PLCs

  • "port:47808 BACnet" - Building automation

  • "port:4840 "OPC UA"" - Modern ICS protocol

  • "port:502 org:"Electric"" - Power infrastructure

  • "port:502 country:US has_vuln:true" - Vulnerable Modbus in US

Effective Patterns:

  • Combine filters: "port:502 tag:ics country:US org:"Water""

  • Use facets for overview: facets="country,org,product"

  • Start broad, narrow down: "port:502" → "port:502 tag:ics" → "port:502 tag:ics Siemens"

Inputs: query (required), facets, page.

shodan_portsA

Get a list of port numbers that Shodan crawls on the Internet. Useful for discovering what protocols are monitored.

Key ICS/SCADA Ports in Shodan:

  • 102: Siemens S7 PLCs

  • 502: Modbus TCP (most common ICS protocol)

  • 1911: Niagara Fox (building automation)

  • 2404: IEC 60870-5-104 (power systems)

  • 4840: OPC UA (modern ICS standard)

  • 20000: DNP3 (utilities/SCADA)

  • 44818: EtherNet/IP (Rockwell/Allen-Bradley)

  • 47808: BACnet (HVAC/building systems)

Use this to verify Shodan monitors your target protocol.

Inputs: no named parameters.

shodan_protocolsB

Get information about the protocols that Shodan supports for querying.

Inputs: no named parameters.

shodan_query_searchB

Search for saved Shodan queries shared by the community. Useful for discovering popular query patterns and learning effective search techniques.

Popular ICS/SCADA Query Topics:

  • "SCADA" - Find SCADA-related searches

  • "ICS" - Industrial control system queries

  • "Modbus" - Modbus protocol queries

  • "PLC" - Programmable logic controller searches

  • "industrial" - General industrial searches

  • "critical infrastructure" - Infrastructure queries

Use community queries to:

  • Learn effective search patterns

  • Discover new reconnaissance techniques

  • Find popular vulnerability searches

  • Get ideas for your own queries

Inputs: query (required), page.

shodan_query_tagsA

Get a list of popular tags for saved Shodan queries. Tags help discover trending search topics and common query categories.

Common ICS/SCADA Related Tags:

  • ics - Industrial Control Systems

  • scada - SCADA systems

  • industrial - Industrial equipment

  • malware - Malware-infected systems

  • webcam - IP cameras (often in facilities)

  • default - Default credentials/configs

Use to browse popular query categories and discover new search angles.

Inputs: size.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as shodan_count for result counts and shodan_host_search for detailed host searches. However, shodan_query_search and shodan_query_tags both relate to saved queries and could be slightly confusing, as they overlap in functionality for discovering community query patterns.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with a 'shodan_' prefix and descriptive verb_noun combinations, such as shodan_api_info and shodan_dns_lookup. This uniformity makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With 11 tools, the server is well-scoped for Shodan's domain, covering API info, searches, DNS lookups, exploits, and query discovery. Each tool serves a clear purpose without redundancy, fitting typical server tool counts of 3-15.

    Completeness4/5

    The tool set provides comprehensive coverage for Shodan's core functionalities, including host and exploit searches, DNS operations, and query exploration. A minor gap is the lack of tools for managing saved searches or alerts, but agents can work around this with existing tools.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-shodan

      Tyler3486
      F
      license
      Not graded
      quality
      A
      maintenance
      Gives AI agents access to Shodan's API and CVEDB for internet reconnaissance, DNS intelligence, and vulnerability analysis. Enables host and device lookups, search queries with facets, DNS resolution, and CVE/CPE intelligence with CVSS, EPSS, and KEV data.
      -

    • mcp-shodan

      IbrahimLopes
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to perform internet reconnaissance against the Shodan API and CVEDB, covering host and port lookups, device searches with facets, DNS and subdomain queries, and CVE/CPE vulnerability intelligence with EPSS and KEV data. Also exposes plan and credit information so agents can stay aware of query costs.
      MIT

    • mcp-shodan

      stijnmorales04935
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to perform internet reconnaissance through the Shodan API: looking up IP addresses and domains for open ports, banners, TLS certificates, DNS records, and searching or counting internet-connected devices with facets. It also delivers CVE/CPE vulnerability intelligence, including CVSS scores, EPSS estimates, and KEV status.
      MIT