Shodan MCP Server

Instructions

Implementation Reference

• src/index.ts:155-184 (handler)

  Core implementation of the Shodan search functionality, making API call to /shodan/host/search, applying sampling and field filtering, handling errors including paid membership requirement.
  async search(query: string, page: number = 1, facets: string[] = [], maxItems: number = 5, selectedFields?: string[]): Promise<any> { try { const params: any = { query, page }; if (facets.length > 0) { params.facets = facets.join(','); } const response = await this.axiosInstance.get("/shodan/host/search", { params }); return this.sampleResponse(response.data, maxItems, selectedFields); } catch (error: unknown) { if (axios.isAxiosError(error)) { if (error.response?.status === 401) { return { error: "Unauthorized: The Shodan search API requires a paid membership. Your API key does not have access to this endpoint.", message: "The search functionality requires a Shodan membership subscription with API access. Please upgrade your Shodan plan to use this feature.", status: 401 }; } throw new McpError( ErrorCode.InternalError, `Shodan API error: ${error.response?.data?.error || error.message}` ); } throw error; } }
• src/index.ts:1317-1374 (handler)

  MCP server tool handler for 'search_shodan': validates input parameters, calls ShodanClient.search, optionally summarizes results, formats response as MCP content.
  case "search_shodan": { const query = String(request.params.arguments?.query); if (!query) { throw new McpError( ErrorCode.InvalidParams, "Search query is required" ); } const page = Number(request.params.arguments?.page) || 1; const facets = Array.isArray(request.params.arguments?.facets) ? request.params.arguments?.facets.map(String) : []; const maxItems = Number(request.params.arguments?.max_items) || 5; const fields = Array.isArray(request.params.arguments?.fields) ? request.params.arguments?.fields.map(String) : undefined; const summarize = Boolean(request.params.arguments?.summarize); try { const searchResults = await shodanClient.search(query, page, facets, maxItems, fields); // Check if we got an error response from the search method if (searchResults.error && searchResults.status === 401) { return { content: [{ type: "text", text: JSON.stringify(searchResults, null, 2) }] }; } if (summarize) { const summary = shodanClient.summarizeResults(searchResults); return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] }; } return { content: [{ type: "text", text: JSON.stringify(searchResults, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error searching Shodan: ${(error as Error).message}` ); } }
• src/index.ts:907-940 (schema)

  Input schema definition for the search_shodan tool, specifying parameters like query, page, facets, max_items, fields, and summarize option.
  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"]
• src/index.ts:904-941 (registration)

  Tool registration in ListTools response: defines name, description, and input schema for search_shodan.
  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"] }
• src/index.ts:52-84 (helper)

  Helper method used by search to sample/truncate large arrays in responses (matches, data, ports) and filter to specific fields, reducing token usage.
  private sampleResponse(data: any, maxItems: number = 5, selectedFields?: string[]): any { if (!data) return data; // Clone the data to avoid modifying the original const result = JSON.parse(JSON.stringify(data)); // Sample matches array if it exists and is longer than maxItems if (result.matches && Array.isArray(result.matches) && result.matches.length > maxItems) { result.matches = result.matches.slice(0, maxItems); result._sample_note = `Response truncated to ${maxItems} matches. Original count: ${data.matches.length}`; } // Sample data array if it exists and is longer than maxItems if (result.data && Array.isArray(result.data) && result.data.length > maxItems) { result.data = result.data.slice(0, maxItems); result._sample_note = `Response truncated to ${maxItems} data items. Original count: ${data.data.length}`; } // Sample ports array if it exists and is longer than maxItems if (result.ports && Array.isArray(result.ports) && result.ports.length > maxItems) { result.ports = result.ports.slice(0, maxItems); if (!result._sample_note) { result._sample_note = `Ports truncated to ${maxItems} items. Original count: ${data.ports.length}`; } } // Filter fields if selectedFields is provided if (selectedFields && selectedFields.length > 0 && typeof result === 'object') { this.filterFields(result, selectedFields); } return result; }