Shodan MCP Server

Instructions

Implementation Reference

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

  Core implementation of the search_cves tool logic in CVEDBClient class, handling API request to CVEDB with filters and error handling.
  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:1841-1886 (handler)

  MCP server tool call handler for 'search_cves' that parses request arguments and delegates to CVEDBClient.searchCves method.
  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:1170-1209 (registration)

  Registration of the search_cves tool in the list of available tools returned by ListToolsRequestSchema, defining its metadata and input schema.
  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:814-814 (helper)

  Instantiation of the CVEDBClient used by the search_cves tool handler.
  const cvedbClient = new CVEDBClient();
• src/index.ts:641-711 (helper)

  CVEDBClient class providing the API client and methods including searchCves for CVE database interactions.
  class CVEDBClient { private axiosInstance: AxiosInstance; constructor() { this.axiosInstance = axios.create({ baseURL: "https://cvedb.shodan.io" }); } /** * Get detailed information about a specific CVE */ async getCveInfo(cveId: string): Promise<any> { try { const response = await this.axiosInstance.get(`/cve/${cveId}`); return response.data; } catch (error: unknown) { if (axios.isAxiosError(error)) { if (error.response?.status === 404) { return { error: "CVE not found", message: `CVE ${cveId} was not found in the database.`, status: 404 }; } throw new McpError( ErrorCode.InternalError, `CVEDB API error: ${error.response?.data?.error || error.message}` ); } throw error; } } /** * Search for vulnerabilities with various 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; } }