Shodan MCP Server

Instructions

Implementation Reference

• src/index.ts:1376-1418 (handler)

  MCP CallToolRequestSchema handler case for 'scan_network_range' that validates input parameters (cidr required), calls shodanClient.scanNetworkRange, handles 401 unauthorized responses from Shodan paid API, and returns JSON-formatted results or errors.

  case "scan_network_range": {
    const cidr = String(request.params.arguments?.cidr);
    if (!cidr) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "CIDR notation is required"
      );
    }
  
    const maxItems = Number(request.params.arguments?.max_items) || 5;
    const fields = Array.isArray(request.params.arguments?.fields)
      ? request.params.arguments?.fields.map(String)
      : undefined;
  
    try {
      const scanResults = await shodanClient.scanNetworkRange(cidr, maxItems, fields);
  
      // Check if we got an error response from the scan method
      if (scanResults.error && scanResults.status === 401) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify(scanResults, null, 2)
          }]
        };
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(scanResults, null, 2)
        }]
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Error scanning network range: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:189-213 (helper)

  Core implementation in ShodanClient class that translates CIDR to Shodan 'net:' query, performs API search, samples/truncates results using sampleResponse, filters fields if specified, and handles API errors including requirement for paid Shodan membership.

  async scanNetworkRange(cidr: string, maxItems: number = 5, selectedFields?: string[]): Promise<any> {
    try {
      // Convert CIDR to Shodan search query format
      const query = `net:${cidr}`;
      const response = await this.axiosInstance.get("/shodan/host/search", {
        params: { query }
      });
      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 network scanning 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:946-966 (schema)

  Zod/JSON schema definition for tool inputs: requires 'cidr' string, optional 'max_items' number for result limiting, optional 'fields' array for response filtering.

  inputSchema: {
    type: "object",
    properties: {
      cidr: {
        type: "string",
        description: "Network range in CIDR notation (e.g., 192.168.1.0/24)"
      },
      max_items: {
        type: "number",
        description: "Maximum number of items to include in results (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'])"
      }
    },
    required: ["cidr"]
  }

• src/index.ts:943-967 (registration)

  Tool registration entry in ListToolsRequestSchema handler's tools array, defining name, description, and complete inputSchema for client discovery.

  {
    name: "scan_network_range",
    description: "Scan a network range (CIDR notation) for devices",
    inputSchema: {
      type: "object",
      properties: {
        cidr: {
          type: "string",
          description: "Network range in CIDR notation (e.g., 192.168.1.0/24)"
        },
        max_items: {
          type: "number",
          description: "Maximum number of items to include in results (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'])"
        }
      },
      required: ["cidr"]
    }
  },