mcp-shodan

Instructions

Implementation Reference

• src/index.ts:365-420 (handler)

  The main handler for the ip_lookup tool within the switch statement in the CallToolRequestSchema handler. It validates input using IpLookupArgsSchema, queries the Shodan host API, formats the response with IP info, location, services (including HTTP details), cloud provider, hostnames, domains, and tags, then returns formatted JSON as text content.
  case "ip_lookup": { const parsedIpArgs = IpLookupArgsSchema.safeParse(args); if (!parsedIpArgs.success) { throw new Error("Invalid ip_lookup arguments"); } const result = await queryShodan(`/shodan/host/${parsedIpArgs.data.ip}`, {}); // Format the response in a user-friendly way const formattedResult = { "IP Information": { "IP Address": result.ip_str, "Organization": result.org, "ISP": result.isp, "ASN": result.asn, "Last Update": result.last_update }, "Location": { "Country": result.country_name, "City": result.city, "Coordinates": `${result.latitude}, ${result.longitude}`, "Region": result.region_code }, "Services": result.ports.map((port: number) => { const service = result.data.find((d: ShodanService) => d.port === port); return { "Port": port, "Protocol": service?.transport || "unknown", "Service": service?.data?.trim() || "No banner", ...(service?.http ? { "HTTP": { "Server": service.http.server, "Title": service.http.title, } } : {}) }; }), "Cloud Provider": result.data[0]?.cloud ? { "Provider": result.data[0].cloud.provider, "Service": result.data[0].cloud.service, "Region": result.data[0].cloud.region } : "Not detected", "Hostnames": result.hostnames || [], "Domains": result.domains || [], "Tags": result.tags || [] }; return { content: [ { type: "text", text: JSON.stringify(formattedResult, null, 2), }, ], }; }
• src/index.ts:146-148 (schema)

  Zod schema defining the input parameters for the ip_lookup tool: requires a single 'ip' string.
  const IpLookupArgsSchema = z.object({ ip: z.string().describe("The IP address to query."), });
• src/index.ts:316-320 (registration)

  Registration of the ip_lookup tool in the ListToolsRequestSchema handler, providing name, detailed description, and converted JSON schema for inputs.
  { name: "ip_lookup", description: "Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available. Returns service banners and HTTP server information when present.", inputSchema: zodToJsonSchema(IpLookupArgsSchema), },
• src/index.ts:199-210 (helper)

  Shared helper function used by ip_lookup to make authenticated API requests to Shodan endpoints, handling errors and logging.
  async function queryShodan(endpoint: string, params: Record<string, any>) { try { const response = await axios.get(`${API_BASE_URL}${endpoint}`, { params: { ...params, key: SHODAN_API_KEY }, timeout: 10000, }); return response.data; } catch (error: any) { const errorMessage = error.response?.data?.error || error.message; logToFile(`Shodan API error: ${errorMessage}`); throw new Error(`Shodan API error: ${errorMessage}`); }
• src/index.ts:104-120 (helper)

  TypeScript interface defining the structure of Shodan host response data, used implicitly in the ip_lookup handler for type safety in formatting.
  interface ShodanHostResponse { ip_str: string; org: string; isp: string; asn: string; last_update: string; country_name: string; city: string; latitude: number; longitude: number; region_code: string; ports: number[]; data: ShodanService[]; hostnames: string[]; domains: string[]; tags: string[]; }