mcp-shodan

Instructions

Implementation Reference

• src/index.ts:421-483 (handler)

  Implements the shodan_search tool handler: parses input arguments, queries the Shodan host/search API, formats the search results including summary, country distribution, and detailed matches with IP info, location, services, and web details.

  case "shodan_search": {
    const parsedSearchArgs = ShodanSearchArgsSchema.safeParse(args);
    if (!parsedSearchArgs.success) {
      throw new Error("Invalid search arguments");
    }
    const result: SearchResponse = await queryShodan("/shodan/host/search", {
      query: parsedSearchArgs.data.query,
      limit: parsedSearchArgs.data.max_results,
    });
  
    // Format the response in a user-friendly way
    const formattedResult = {
      "Search Summary": {
        "Query": parsedSearchArgs.data.query,
        "Total Results": result.total,
        "Results Returned": result.matches.length
      },
      "Country Distribution": result.facets?.country?.map(country => ({
        "Country": country.value,
        "Count": country.count,
        "Percentage": `${((country.count / result.total) * 100).toFixed(2)}%`
      })) || [],
      "Matches": result.matches.map(match => ({
        "Basic Information": {
          "IP Address": match.ip_str,
          "Organization": match.org,
          "ISP": match.isp,
          "ASN": match.asn,
          "Last Update": match.timestamp
        },
        "Location": {
          "Country": match.location.country_name,
          "City": match.location.city || "Unknown",
          "Region": match.location.region_code || "Unknown",
          "Coordinates": `${match.location.latitude}, ${match.location.longitude}`
        },
        "Service Details": {
          "Port": match.port,
          "Transport": match.transport,
          "Product": match.product || "Unknown",
          "Version": match.version || "Unknown",
          "CPE": match.cpe || []
        },
        "Web Information": match.http ? {
          "Server": match.http.server,
          "Title": match.http.title,
          "Robots.txt": match.http.robots ? "Present" : "Not found",
          "Sitemap": match.http.sitemap ? "Present" : "Not found"
        } : "No HTTP information",
        "Hostnames": match.hostnames,
        "Domains": match.domains
      }))
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(formattedResult, null, 2),
        },
      ],
    };
  }

• src/index.ts:150-157 (schema)

  Zod schema defining input for shodan_search: query string and optional max_results (default 10).

  const ShodanSearchArgsSchema = z.object({
    query: z.string().describe("Search query for Shodan."),
    max_results: z
      .number()
      .optional()
      .default(10)
      .describe("Maximum results to return."),
  });

• src/index.ts:321-325 (registration)

  Registers the shodan_search tool in the MCP server's tool list with name, description, and converted JSON schema.

  {
    name: "shodan_search",
    description: "Search Shodan's database of internet-connected devices. Returns detailed information about matching devices including services, vulnerabilities, and geographic distribution. Supports advanced search filters and returns country-based statistics.",
    inputSchema: zodToJsonSchema(ShodanSearchArgsSchema),
  },