Shodan MCP Server

Overview Schema Related Servers Score Discussions

search_cves

Search for vulnerabilities using filters like CPE, product name, date range, and Known Exploited Vulnerabilities to identify security risks.

Instructions

Search for vulnerabilities with various filters

Input Schema

TableJSON Schema

Name	Required	Description
`cpe23`	No	CPE 2.3 string to search for (e.g., 'cpe:2.3:a:apache:log4j:*')
`product`	No	Product name to search for vulnerabilities (e.g., 'apache', 'windows')
`is_kev`	No	Filter for Known Exploited Vulnerabilities only
`sort_by_epss`	No	Sort results by EPSS score (Exploit Prediction Scoring System)
`start_date`	No	Start date for filtering CVEs (YYYY-MM-DD format)
`end_date`	No	End date for filtering CVEs (YYYY-MM-DD format)
`limit`	No	Maximum number of results to return (default: 10)
`skip`	No	Number of results to skip for pagination (default: 0)

Implementation Reference

src/index.ts:678-711 (handler)

Core handler function in CVEDBClient that performs the CVE search by querying the CVEDB API with provided filters.

async searchCves(options: {
  cpe23?: string;
  product?: string;
  is_kev?: boolean;
  sort_by_epss?: boolean;
  start_date?: string;
  end_date?: string;
  limit?: number;
  skip?: number;
} = {}): Promise<any> {
  try {
    const params: any = {};

    if (options.cpe23) params.cpe23 = options.cpe23;
    if (options.product) params.product = options.product;
    if (options.is_kev !== undefined) params.is_kev = options.is_kev;
    if (options.sort_by_epss !== undefined) params.sort_by_epss = options.sort_by_epss;
    if (options.start_date) params.start_date = options.start_date;
    if (options.end_date) params.end_date = options.end_date;
    if (options.limit) params.limit = options.limit;
    if (options.skip) params.skip = options.skip;

    const response = await this.axiosInstance.get("/cves", { params });
    return response.data;
  } catch (error: unknown) {
    if (axios.isAxiosError(error)) {
      throw new McpError(
        ErrorCode.InternalError,
        `CVEDB API error: ${error.response?.data?.error || error.message}`
      );
    }
    throw error;
  }
}

src/index.ts:1169-1208 (schema)

Tool schema definition including input schema for search_cves in the ListToolsRequestSchema handler.

{
  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)"
      }
    }
  }

src/index.ts:1841-1886 (handler)

MCP server handler case for search_cves tool that parses arguments and calls CVEDBClient.searchCves.

case "search_cves": {
  const options: any = {};

  if (request.params.arguments?.cpe23) {
    options.cpe23 = String(request.params.arguments.cpe23);
  }
  if (request.params.arguments?.product) {
    options.product = String(request.params.arguments.product);
  }
  if (request.params.arguments?.is_kev !== undefined) {
    options.is_kev = Boolean(request.params.arguments.is_kev);
  }
  if (request.params.arguments?.sort_by_epss !== undefined) {
    options.sort_by_epss = Boolean(request.params.arguments.sort_by_epss);
  }
  if (request.params.arguments?.start_date) {
    options.start_date = String(request.params.arguments.start_date);
  }
  if (request.params.arguments?.end_date) {
    options.end_date = String(request.params.arguments.end_date);
  }
  if (request.params.arguments?.limit) {
    options.limit = Number(request.params.arguments.limit);
  }
  if (request.params.arguments?.skip) {
    options.skip = Number(request.params.arguments.skip);
  }

  try {
    const cveResults = await cvedbClient.searchCves(options);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(cveResults, null, 2)
      }]
    };
  } catch (error) {
    if (error instanceof McpError) {
      throw error;
    }
    throw new McpError(
      ErrorCode.InternalError,
      `Error searching CVEs: ${(error as Error).message}`
    );
  }
}

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

Registration of all tools including search_cves via ListToolsRequestSchema handler that returns 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)"
            }
          }
        }
      }
    ]
  };
});

src/index.ts:641-648 (helper)

CVEDBClient class that provides the API client instance used by search_cves and other CVE tools.

class CVEDBClient {
  private axiosInstance: AxiosInstance;

  constructor() {
    this.axiosInstance = axios.create({
      baseURL: "https://cvedb.shodan.io"
    });
  }

Tool Definition Quality

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It mentions 'various filters' but doesn't describe return format, pagination behavior, rate limits, authentication needs, or what happens with no results. For a search tool with 8 parameters and no annotation coverage, this is inadequate.

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 with zero wasted words. It's appropriately sized and front-loaded, directly stating the core functionality without unnecessary elaboration.

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 complexity (8 parameters, search functionality), lack of annotations, and no output schema, the description is insufficiently complete. It doesn't explain what the search returns, how results are structured, or important behavioral aspects like default behaviors or error conditions.

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?

Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description adds no additional parameter semantics beyond mentioning 'various filters', which is already implied by the schema. Baseline score of 3 is appropriate when the schema does all the work.

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 as 'Search for vulnerabilities with various filters', which specifies the verb (search) and resource (vulnerabilities). It distinguishes from some siblings like 'get_cve_info' or 'get_kev_cves' by emphasizing the filtering capability, though it doesn't explicitly differentiate from 'search_iot_devices' or other search tools.

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 sibling tools like 'get_kev_cves' (for KEV-only searches) or 'get_cves_by_epss' (for EPSS-focused queries), nor does it specify prerequisites, contexts, or exclusions for usage.

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