Shodan MCP Server

Instructions

Implementation Reference

• src/index.ts:218-271 (handler)

  Core implementation of the get_ssl_info tool. Performs Shodan search with query 'ssl:{domain}', processes matches to extract SSL certificate details including subject, issuer, expiration dates, fingerprint, cipher, and version. Handles sampling and errors.

  async getSslInfo(domain: string): Promise<any> {
    try {
      // Use Shodan search to find SSL certificates for the domain
      const query = `ssl:${domain}`;
      const response = await this.axiosInstance.get("/shodan/host/search", {
        params: { query }
      });
  
      // Extract and format SSL certificate information
      const results = this.sampleResponse(response.data, 5);
  
      // Process the results to extract SSL certificate details
      if (results.matches && results.matches.length > 0) {
        const sslInfo = results.matches.map((match: any) => {
          if (match.ssl && match.ssl.cert) {
            return {
              ip: match.ip_str,
              port: match.port,
              subject: match.ssl.cert.subject,
              issuer: match.ssl.cert.issuer,
              expires: match.ssl.cert.expires,
              issued: match.ssl.cert.issued,
              fingerprint: match.ssl.cert.fingerprint,
              cipher: match.ssl.cipher,
              version: match.ssl.version
            };
          }
          return null;
        }).filter(Boolean);
  
        return {
          total: sslInfo.length,
          certificates: sslInfo
        };
      }
  
      return { total: 0, certificates: [] };
    } 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 SSL certificate lookup 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:1420-1457 (handler)

  MCP server CallToolRequestSchema handler for 'get_ssl_info'. Validates domain input, invokes ShodanClient.getSslInfo, handles 401 errors gracefully, and returns JSON-formatted response.

  case "get_ssl_info": {
    const domain = String(request.params.arguments?.domain);
    if (!domain) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Domain name is required"
      );
    }
  
    try {
      const sslInfo = await shodanClient.getSslInfo(domain);
  
      // Check if we got an error response from the SSL info method
      if (sslInfo.error && sslInfo.status === 401) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify(sslInfo, null, 2)
          }]
        };
      }
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(sslInfo, null, 2)
        }]
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Error getting SSL certificate information: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:968-981 (registration)

  Registration of the 'get_ssl_info' tool in the ListToolsRequestSchema response, including name, description, and input schema definition.

  {
    name: "get_ssl_info",
    description: "Get SSL certificate information for a domain",
    inputSchema: {
      type: "object",
      properties: {
        domain: {
          type: "string",
          description: "Domain name to look up SSL certificates for (e.g., example.com)"
        }
      },
      required: ["domain"]
    }
  },

• src/index.ts:971-980 (schema)

  Input schema definition for the get_ssl_info tool, specifying a required 'domain' string parameter.

  inputSchema: {
    type: "object",
    properties: {
      domain: {
        type: "string",
        description: "Domain name to look up SSL certificates for (e.g., example.com)"
      }
    },
    required: ["domain"]
  }