Shodan MCP Server

Instructions

Implementation Reference

• src/index.ts:1459-1501 (handler)

  MCP CallTool handler for 'search_iot_devices' that extracts parameters, calls ShodanClient.searchIotDevices method, handles errors, and returns JSON-formatted results.

  case "search_iot_devices": {
    const deviceType = String(request.params.arguments?.device_type);
    if (!deviceType) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Device type is required"
      );
    }
  
    const country = request.params.arguments?.country
      ? String(request.params.arguments.country)
      : undefined;
    const maxItems = Number(request.params.arguments?.max_items) || 5;
  
    try {
      const iotDevices = await shodanClient.searchIotDevices(deviceType, country, maxItems);
  
      // Check if we got an error response from the IoT devices search method
      if (iotDevices.error && iotDevices.status === 401) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify(iotDevices, null, 2)
          }]
        };
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(iotDevices, null, 2)
        }]
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Error searching for IoT devices: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:276-329 (helper)

  ShodanClient.searchIotDevices method: constructs Shodan search query for IoT devices, fetches data from Shodan API, samples results, extracts relevant fields, and handles API errors.

  async searchIotDevices(deviceType: string, country?: string, maxItems: number = 5): Promise<any> {
    try {
      // Build query based on device type and optional country
      let query = `"${deviceType}"`;
      if (country) {
        query += ` country:${country}`;
      }
  
      const response = await this.axiosInstance.get("/shodan/host/search", {
        params: { query }
      });
  
      const results = this.sampleResponse(response.data, maxItems);
  
      // Extract relevant IoT device information
      if (results.matches && results.matches.length > 0) {
        const devices = results.matches.map((match: any) => {
          return {
            ip: match.ip_str,
            port: match.port,
            organization: match.org,
            location: match.location,
            hostnames: match.hostnames,
            product: match.product,
            version: match.version,
            timestamp: match.timestamp
          };
        });
  
        return {
          total_found: results.total,
          sample_size: devices.length,
          devices: devices
        };
      }
  
      return { total_found: 0, devices: [] };
    } 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 IoT device 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:982-1002 (schema)

  Tool schema definition including input schema for 'search_iot_devices' registered in ListTools handler.

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

• src/index.ts:982-1002 (registration)

  Registration of 'search_iot_devices' tool in the ListToolsRequestSchema response, defining name, description, and input schema.

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