Shodan MCP Server

Overview Schema Related Servers Score Discussions

reverse_dns_lookup

Retrieve hostnames associated with IP addresses through reverse DNS lookup to identify domain names linked to specific network endpoints.

Instructions

Get hostnames for IP addresses using reverse DNS lookup

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ips`	Yes	List of IP addresses to lookup (e.g., ['8.8.8.8', '1.1.1.1'])

Implementation Reference

src/index.ts:1722-1748 (handler)

MCP server tool handler for 'reverse_dns_lookup'. Validates input ips array and calls shodanClient.reverseDnsLookup, returning JSON results.

case "reverse_dns_lookup": {
  const ips = request.params.arguments?.ips;
  if (!Array.isArray(ips) || ips.length === 0) {
    throw new McpError(
      ErrorCode.InvalidParams,
      "IPs array is required"
    );
  }

  try {
    const reverseDnsResults = await shodanClient.reverseDnsLookup(ips.map(String));
    return {
      content: [{
        type: "text",
        text: JSON.stringify(reverseDnsResults, null, 2)
      }]
    };
  } catch (error) {
    if (error instanceof McpError) {
      throw error;
    }
    throw new McpError(
      ErrorCode.InternalError,
      `Error performing reverse DNS lookup: ${(error as Error).message}`
    );
  }
}

src/index.ts:510-527 (helper)

ShodanClient method implementing reverse DNS lookup via Shodan API /dns/reverse endpoint.

 * Reverse DNS lookup - get hostnames for IP addresses
 */
async reverseDnsLookup(ips: string[]): Promise<any> {
  try {
    const response = await this.axiosInstance.get("/dns/reverse", {
      params: { ips: ips.join(',') }
    });
    return response.data;
  } catch (error: unknown) {
    if (axios.isAxiosError(error)) {
      throw new McpError(
        ErrorCode.InternalError,
        `Shodan API error: ${error.response?.data?.error || error.message}`
      );
    }
    throw error;
  }
}

src/index.ts:1104-1119 (schema)

Input schema definition for the reverse_dns_lookup tool in ListTools response.

{
  name: "reverse_dns_lookup",
  description: "Get hostnames for IP addresses using reverse DNS lookup",
  inputSchema: {
    type: "object",
    properties: {
      ips: {
        type: "array",
        items: {
          type: "string"
        },
        description: "List of IP addresses to lookup (e.g., ['8.8.8.8', '1.1.1.1'])"
      }
    },
    required: ["ips"]
  }

src/index.ts:875-1280 (registration)

Tool registration via ListToolsRequestSchema handler including reverse_dns_lookup in the tools list.

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_host_info",
        description: "Get detailed information about a specific IP address",
        inputSchema: {
          type: "object",
          properties: {
            ip: {
              type: "string",
              description: "IP address to look up"
            },
            max_items: {
              type: "number",
              description: "Maximum number of items to include in arrays (default: 5)"
            },
            fields: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name'])"
            }
          },
          required: ["ip"]
        }
      },
      {
        name: "search_shodan",
        description: "Search Shodan's database for devices and services",
        inputSchema: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "Shodan search query (e.g., 'apache country:US')"
            },
            page: {
              type: "number",
              description: "Page number for results pagination (default: 1)"
            },
            facets: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of facets to include in the search results (e.g., ['country', 'org'])"
            },
            max_items: {
              type: "number",
              description: "Maximum number of items to include in arrays (default: 5)"
            },
            fields: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name'])"
            },
            summarize: {
              type: "boolean",
              description: "Whether to return a summary of the results instead of the full data (default: false)"
            }
          },
          required: ["query"]
        }
      },
      {
        name: "scan_network_range",
        description: "Scan a network range (CIDR notation) for devices",
        inputSchema: {
          type: "object",
          properties: {
            cidr: {
              type: "string",
              description: "Network range in CIDR notation (e.g., 192.168.1.0/24)"
            },
            max_items: {
              type: "number",
              description: "Maximum number of items to include in results (default: 5)"
            },
            fields: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of fields to include in the results (e.g., ['ip_str', 'ports', 'location.country_name'])"
            }
          },
          required: ["cidr"]
        }
      },
      {
        name: "get_ssl_info",
        description: "Get SSL certificate information for a domain",
        inputSchema: {
          type: "object",
          properties: {
            domain: {
              type: "string",
              description: "Domain name to look up SSL certificates for (e.g., example.com)"
            }
          },
          required: ["domain"]
        }
      },
      {
        name: "search_iot_devices",
        description: "Search for specific types of IoT devices",
        inputSchema: {
          type: "object",
          properties: {
            device_type: {
              type: "string",
              description: "Type of IoT device to search for (e.g., 'webcam', 'router', 'smart tv')"
            },
            country: {
              type: "string",
              description: "Optional country code to limit search (e.g., 'US', 'DE')"
            },
            max_items: {
              type: "number",
              description: "Maximum number of items to include in results (default: 5)"
            }
          },
          required: ["device_type"]
        }
      },
      {
        name: "get_host_count",
        description: "Get the count of hosts matching a search query without consuming query credits",
        inputSchema: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "Shodan search query to count hosts for"
            },
            facets: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of facets to include in the count results (e.g., ['country', 'org'])"
            }
          },
          required: ["query"]
        }
      },
      {
        name: "list_search_facets",
        description: "List all available search facets that can be used with Shodan queries",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "list_search_filters",
        description: "List all available search filters that can be used in Shodan queries",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "parse_search_tokens",
        description: "Parse a search query to understand which filters and parameters are being used",
        inputSchema: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "Shodan search query to parse and analyze"
            }
          },
          required: ["query"]
        }
      },
      {
        name: "list_ports",
        description: "List all ports that Shodan crawls on the Internet",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "list_protocols",
        description: "List all protocols that can be used when performing on-demand Internet scans",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "get_api_info",
        description: "Get information about your API plan including credits and limits",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "get_my_ip",
        description: "Get your current IP address as seen from the Internet",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "dns_lookup",
        description: "Resolve hostnames to IP addresses using DNS lookup",
        inputSchema: {
          type: "object",
          properties: {
            hostnames: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of hostnames to resolve (e.g., ['google.com', 'facebook.com'])"
            }
          },
          required: ["hostnames"]
        }
      },
      {
        name: "reverse_dns_lookup",
        description: "Get hostnames for IP addresses using reverse DNS lookup",
        inputSchema: {
          type: "object",
          properties: {
            ips: {
              type: "array",
              items: {
                type: "string"
              },
              description: "List of IP addresses to lookup (e.g., ['8.8.8.8', '1.1.1.1'])"
            }
          },
          required: ["ips"]
        }
      },
      {
        name: "get_domain_info",
        description: "Get comprehensive domain information including subdomains and DNS records",
        inputSchema: {
          type: "object",
          properties: {
            domain: {
              type: "string",
              description: "Domain name to lookup (e.g., 'google.com')"
            },
            history: {
              type: "boolean",
              description: "Include historical DNS data (default: false)"
            },
            type: {
              type: "string",
              description: "DNS record type filter (A, AAAA, CNAME, NS, SOA, MX, TXT)"
            },
            page: {
              type: "number",
              description: "Page number for pagination (default: 1)"
            }
          },
          required: ["domain"]
        }
      },
      {
        name: "get_account_profile",
        description: "Get account profile information including membership status and credits",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "get_cve_info",
        description: "Get detailed information about a specific CVE",
        inputSchema: {
          type: "object",
          properties: {
            cve_id: {
              type: "string",
              description: "CVE ID to look up (e.g., 'CVE-2021-44228')"
            }
          },
          required: ["cve_id"]
        }
      },
      {
        name: "search_cves",
        description: "Search for vulnerabilities with various filters",
        inputSchema: {
          type: "object",
          properties: {
            cpe23: {
              type: "string",
              description: "CPE 2.3 string to search for (e.g., 'cpe:2.3:a:apache:log4j:*')"
            },
            product: {
              type: "string",
              description: "Product name to search for vulnerabilities (e.g., 'apache', 'windows')"
            },
            is_kev: {
              type: "boolean",
              description: "Filter for Known Exploited Vulnerabilities only"
            },
            sort_by_epss: {
              type: "boolean",
              description: "Sort results by EPSS score (Exploit Prediction Scoring System)"
            },
            start_date: {
              type: "string",
              description: "Start date for filtering CVEs (YYYY-MM-DD format)"
            },
            end_date: {
              type: "string",
              description: "End date for filtering CVEs (YYYY-MM-DD format)"
            },
            limit: {
              type: "number",
              description: "Maximum number of results to return (default: 10)"
            },
            skip: {
              type: "number",
              description: "Number of results to skip for pagination (default: 0)"
            }
          }
        }
      },
      {
        name: "get_cpes",
        description: "Get Common Platform Enumeration (CPE) information for products",
        inputSchema: {
          type: "object",
          properties: {
            product: {
              type: "string",
              description: "Product name to search for (e.g., 'apache', 'windows')"
            },
            vendor: {
              type: "string",
              description: "Vendor name to filter by (e.g., 'microsoft', 'apache')"
            },
            version: {
              type: "string",
              description: "Version to filter by (e.g., '2.4.1')"
            },
            limit: {
              type: "number",
              description: "Maximum number of results to return (default: 10)"
            },
            skip: {
              type: "number",
              description: "Number of results to skip for pagination (default: 0)"
            }
          }
        }
      },
      {
        name: "get_newest_cves",
        description: "Get the newest vulnerabilities from the CVE database",
        inputSchema: {
          type: "object",
          properties: {
            limit: {
              type: "number",
              description: "Maximum number of results to return (default: 10)"
            }
          }
        }
      },
      {
        name: "get_kev_cves",
        description: "Get Known Exploited Vulnerabilities (KEV) from CISA",
        inputSchema: {
          type: "object",
          properties: {
            limit: {
              type: "number",
              description: "Maximum number of results to return (default: 10)"
            }
          }
        }
      },
      {
        name: "get_cves_by_epss",
        description: "Get CVEs sorted by EPSS score (Exploit Prediction Scoring System)",
        inputSchema: {
          type: "object",
          properties: {
            limit: {
              type: "number",
              description: "Maximum number of results to return (default: 10)"
            }
          }
        }
      }
    ]
  };
});

Tool Definition Quality

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get hostnames') but doesn't describe what happens if IPs are invalid, rate limits, authentication needs, error handling, or output format. For a tool with no annotations, this leaves significant gaps in understanding how it behaves beyond the basic operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence: 'Get hostnames for IP addresses using reverse DNS lookup'. It's front-loaded with the core purpose, uses precise terminology, and has zero wasted words. Every part of the sentence contributes directly to understanding the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (network operation with one parameter) and lack of annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like error cases, performance, or result format. For a tool that performs external lookups, more context on reliability and output structure would be helpful, making this inadequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'IP addresses' which aligns with the 'ips' parameter in the schema. Schema description coverage is 100%, with the schema providing a clear example. The description adds minimal value beyond the schema, as it doesn't explain parameter constraints (e.g., IPv4 vs. IPv6, format requirements) or usage nuances. Baseline 3 is appropriate given high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get hostnames for IP addresses using reverse DNS lookup'. It specifies the verb ('Get'), resource ('hostnames'), and input ('IP addresses'), distinguishing it from the sibling 'dns_lookup' which likely performs forward DNS lookups. However, it doesn't explicitly contrast with 'dns_lookup' or other siblings, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over 'dns_lookup' or other network-related tools like 'get_host_info' or 'scan_network_range'. There's no context about prerequisites, limitations, or typical use cases, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Cyreslab-AI/shodan-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server