Tools Reference

This comprehensive reference covers all 17 tools available in the WhoisXML API MCP Server.

An example of Claude Desktop displaying some of the MCP Server Tools

Overview

The WhoisXML API MCP Server provides 17 different tools for querying various types of domain, IP, and DNS information. Each tool is designed to interact with specific WhoisXMLAPI endpoints and provides structured data responses.

Tools List

  1. whois - Domain WHOIS information
  2. categorization - Domain categorization
  3. email_verification - Email verification
  4. reverse_ip - Reverse IP lookup
  5. reverse_mx - Reverse MX lookup
  6. reverse_ns - Reverse NS lookup
  7. reverse_dns - Reverse DNS lookup
  8. reverse_whois - Reverse WHOIS lookup
  9. whois_history - WHOIS history
  10. subdomain_lookup - Subdomain lookup
  11. domain_and_subdomain_discovery - Domain and subdomain discovery
  12. dns_lookup - DNS lookup
  13. dns_history - DNS history
  14. ipgeolocation - IP geolocation
  15. ip_netblocks - IP netblocks
  16. ssl_certificates - SSL certificates
  17. threat_intelligence - Threat intelligence

whois

Description: Get WHOIS information for a domain including registration dates, status, nameservers, and contact info.

whois

Arguments

  • domain (string, required) - Domain name to query
  • query_type (string, optional) - Query type: "auto", "whois", or "rdap". "rdap" is only supported in domain queries but might not be available for all domains. "auto" will always choose correctly Default: "auto"
  • prefer_refresh_even_if_incomplete (boolean, optional) - If true, provides most up-to-date but potentially incomplete data Default: false
  • force_refresh (boolean, optional) - If true, forces hard refresh. Costs 5 API calls Default: false
  • include_domain_availability (boolean, optional) - If true, includes domain availability status Default: false
  • include_ip_for_domain_queried (boolean, optional) - If true, includes hosting IP address for the domain Default: false
  • get_host_ip_whois_on_no_domain_data (boolean, optional) - If true, returns host IP WHOIS when domain WHOIS is unavailable Default: false
  • get_registrar_proxy_data (boolean, optional) - If true, includes registrar WHOIS proxy info in "privateWhoisProxy" Default: false
  • fetch_whois_from_registry_only (boolean, optional) - If true, returns only registry WHOIS data, not registrar data Default: false
  • remove_raw_text (boolean, optional) - If true, removes raw text from WHOIS output Default: false
  • parse_registry_raw_text (boolean, optional) - If true, provides parsed format for registry information Default: false
  • parse_registrar_raw_text (boolean, optional) - If true, provides parsed format for registrar information Default: false

categorization

Description: Get domain categorization information for a URL or domain name.

categorization

Arguments

  • url (string, required) - URL or domain name to categorize
  • minimum_confidence (number, optional) - Minimum confidence for predictions. Higher value = fewer false positives. Range: 0.0-1.0 Default: 0.55

email_verification

Description: Verify if an email address is legitimate. Checks syntax, SMTP, DNS, free/disposable status, and catch-all configuration.

email_verification

Arguments

  • email (string, required) - Email address to verify
  • validate_using_dns (boolean, optional) - Validate using DNS records Default: true
  • validate_using_smtp (boolean, optional) - Validate using SMTP Default: true
  • check_if_email_is_catch_all (boolean, optional) - Check if email is catch-all Default: true
  • check_if_email_is_free (boolean, optional) - Check if email is free Default: true
  • check_if_email_is_disposable (boolean, optional) - Check if email is disposable Default: true

reverse_ip

Description: Find all domains sharing the same IP address and connection dates.

reverse_ip

Arguments

  • ipv4_address (string, required) - IPv4 address to search
  • from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
  • include_additional_checks (boolean, optional) - If true, performs additional DNS checks (wildcard, domain activeness). Slower but more detailed Default: false
  • preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_mx

Description: Find all services sharing the same MX server and connection dates.

reverse_mx

Arguments

  • mx_hostname (string, required) - MX hostname to search
  • from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
  • include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost Default: false
  • preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_ns

Description: Find all services sharing the same NS nameserver and connection dates.

reverse_ns

Arguments

  • ns_hostname (string, required) - NS nameserver hostname to search
  • from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
  • include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost Default: false
  • preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_dns

Description: Find DNS records matching search criteria. Returns domains and DNS record values. Must use wildcards in the "term" field for partial matches otherwise the search will be exact.

reverse_dns

Arguments

  • record_type (string, required) - DNS record type: "soa", "txt", or "cname". Case insensitive
  • terms (array, required) - Search terms array defining what to search for in DNS records. Must use wildcards for partial matches otherwise the search will be exact
  • limit (number, optional) - Maximum records to return. Recommended to start with 10 and increase if needed. Max: 1000. Range: 1-1000 Default: 10
  • include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost Default: false
  • preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

Terms Array Structure

Each term in the terms array should contain:

  • field (string, required) - Field to search: "domain" or "value"
  • term (string, required) - Search keyword. Supports wildcards
  • exclude (boolean, optional) - If true, excludes matching records from results Default: false

reverse_whois

Description: Find domains containing specific search terms in their whois records.

reverse_whois

Arguments

  • included_search_terms (string, required) - Comma-separated search terms to include. Max 4 items. Case insensitive
  • excluded_search_terms (string, optional) - Comma-separated search terms to exclude. Max 4 items. Case insensitive
  • search_type (string, optional) - Search type: "current" or "historic". "current" searches current records, "historic" searches all records
  • count_only (boolean, optional) - If true, returns only count (no credit usage). If false, returns domain list Default: false
  • punycode (boolean, optional) - If true, encodes domain names to Punycode Default: false
  • include_audit_dates (boolean, optional) - If true, includes domain list and last audit date Default: true
  • created_date_from (string, optional) - Search domains created after this date. Format: YYYY-MM-DD
  • created_date_to (string, optional) - Search domains created before this date. Format: YYYY-MM-DD
  • updated_date_from (string, optional) - Search domains updated after this date. Format: YYYY-MM-DD
  • updated_date_to (string, optional) - Search domains updated before this date. Format: YYYY-MM-DD
  • search_after (string, optional) - Pagination needle from previous page's "nextPageSearchAfter" value

whois_history

Description: Get historical WHOIS records for a domain including past nameservers, contacts, and registrar info. Supports pagination for large result sets.

whois_history

Arguments

  • domain_name (string, required) - Domain name to search
  • limit (number, optional) - Number of records to return per page. Range: 1-100 Default: 100
  • next_page_token (string, optional) - Token from the previous response's next_page_token field to fetch the next page. Note: Only next_page_token is accepted - do not use search_after, page_token, or cursor
  • preview_mode (boolean, optional) - If true, returns only the number of records but no data. It's 50 times cheaper than the full response Default: false
  • skip_live_whois_records (boolean, optional) - If true, excludes most recent WHOIS record. Faster response Default: false
  • since_date (string, optional) - Return results from this date onwards. Format: YYYY-MM-DD
  • created_date_from (string, optional) - Search domains created after this date. Format: YYYY-MM-DD
  • created_date_to (string, optional) - Search domains created before this date. Format: YYYY-MM-DD
  • updated_date_from (string, optional) - Search domains updated after this date. Format: YYYY-MM-DD
  • updated_date_to (string, optional) - Search domains updated before this date. Format: YYYY-MM-DD
  • expired_date_from (string, optional) - Search domains expired after this date. Format: YYYY-MM-DD
  • expired_date_to (string, optional) - Search domains expired before this date. Format: YYYY-MM-DD

Pagination

Responses include a pagination object with:

  • total_count - Total number of records available
  • page_number - Current page number (1-indexed)
  • limit - Number of records in current page
  • has_more - Whether more pages are available
  • next_page_token - Token to use for the next page (only present if has_more is true). Pass this value as the next_page_token parameter to fetch the next page

subdomain_lookup

Description: Find all subdomains for a domain with first and last seen timestamps. Supports pagination for large result sets.

subdomain_lookup

Arguments

  • domain_name (string, required) - Domain name to lookup subdomains for
  • limit (number, optional) - Number of subdomains to return per page. Range: 1-500 Default: 500
  • next_page_token (string, optional) - Token from the previous response's next_page_token field to fetch the next page. Note: Only next_page_token is accepted - do not use search_after, page_token, or cursor

Pagination

Responses include a pagination object with:

  • total_count - Total number of subdomains found
  • page_number - Current page number (1-indexed)
  • limit - Number of subdomains in current page
  • has_more - Whether more pages are available
  • next_page_token - Token to use for the next page (only present if has_more is true). Pass this value as the next_page_token parameter to fetch the next page

domain_and_subdomain_discovery

Description: Find domains and subdomains matching search terms. Must use wildcards for partial matches otherwise the search will be exact.

domain_and_subdomain_discovery

Arguments

  • domain_search_terms (string, optional) - Comma-separated domain search terms. Max 4 items. Case insensitive. Must use wildcards for partial matches otherwise the search will be exact
  • domain_search_terms_exclude (string, optional) - Comma-separated domain search terms to exclude. Max 4 items. Case insensitive
  • subdomains_search_terms (string, optional) - Comma-separated subdomain search terms. Max 4 items. Case insensitive
  • subdomains_search_terms_exclude (string, optional) - Comma-separated subdomain search terms to exclude. Max 4 items. Case insensitive
  • since (string, optional) - Search domains/subdomains discovered since this date. Format: YYYY-MM-DD

dns_lookup

Description: Perform DNS queries for a domain (A, NS, SOA, MX, etc.).

dns_lookup

Arguments

  • domain_name (string, required) - Domain name to query
  • query_type (string, optional) - Comma-separated DNS query types (A, MX, NS, SOA, etc.) or "all" Default: "A"

dns_history

Description: Get historical DNS records for a domain (forward) or find domains associated with an IP (reverse).

dns_history

Arguments

  • search_type (string, required) - Search type: "forward" or "reverse"
  • record_type (string, required) - DNS record type: "a" or "aaaa". Case insensitive
  • domain_name (string, conditional) - Required if "forward" search type. Domain name to search
  • ip_address (string, conditional) - Required if "reverse" search type. IP address to search. IPv4 returns A records, IPv6 returns AAAA records
  • limit (number, required) - Maximum records to return. Range: 1-10000

ipgeolocation

Description: Get location data for IP addresses, domains, or email addresses. Uses caller's IP if no address provided.

ipgeolocation

Arguments

  • ip_address (string, optional) - IPv4 or IPv6 address. Cannot be used with domain_name or email_address
  • domain_name (string, optional) - Domain address. Cannot be used with ip_address or email_address
  • email_address (string, optional) - Email address. Cannot be used with ip_address or domain_name
  • reverse_ip (boolean, optional) - If true, returns 5 domains associated with the IP address Default: false

Note: Only one of ip_address, domain_name, or email_address can be provided. If none are provided, the caller's IP address will be used.

ip_netblocks

Description: Get IP netblock information including IP ranges, ASN, and organization data.

ip_netblocks

Arguments

  • ip_address (string, optional) - IPv4 or IPv6 address to search
  • organizations (string, optional) - Comma-separated organization search terms
  • asn (string, optional) - ASN number to search
  • netmask_value (number, optional) - Netmask value: 0-32 for IPv4, 0-128 for IPv6
  • limit (number, optional) - Maximum records per page. Max: 1000. Range: 1-1000 Default: 100
  • from_needle (string, optional) - Pagination needle from previous page's "inetnum" response

Note: At least one of ip_address, organizations, or asn must be provided.

ssl_certificates

Description: Check TLS certificate chain for a domain to analyze certificate validity, expiration, and chain structure

ssl_certificates

Arguments

  • domain (string, required) - The domain name to check TLS certificate for (e.g., example.com)
  • include_chain (boolean, optional) - Whether to include the full certificate chain in the response Default: false
  • use_fresh_data (boolean, optional) - Whether to get fresh data instead of cached results Default: false

threat_intelligence

Description: Check if IoCs (domains, URLs, IPs, CIDRs, hashes) are associated with malicious activity.

threat_intelligence

Arguments

  • search_term (string, required) - IoC to check: domain, URL, IP, CIDR, or hash. Supports wildcards for domains, URLs, IPs
  • limit (number, optional) - Maximum records per page. Max: 10,000. Every 100 records = 1 credit. Range: 1-10000

Authentication

All tools require proper authentication via the WhoisXMLAPI. The server must be configured with valid API credentials for the WhoisXMLAPI service.

Response Format

All tools return responses in JSON format. The structure of the response depends on the specific tool and the data returned by the WhoisXMLAPI.

Rate Limits and Credits

  • Each tool call consumes API credits based on WhoisXMLAPI pricing
  • Rate limits are enforced by the WhoisXMLAPI service
  • Failed requests typically don't consume credits

Best Practices

  1. Start broad: Use basic tools like whois and dns_lookup first
  2. Follow leads: Use results to inform subsequent queries
  3. Combine tools: Use multiple tools for comprehensive analysis
  4. Check history: Use historical tools to understand changes over time
  5. Verify results: Cross-reference data from multiple tools

Error Handling

Common error scenarios:

  • Invalid input: Malformed domains or IP addresses
  • Rate limiting: Too many requests in a short timeframe
  • Insufficient credits: Account lacks sufficient API credits
  • Network issues: Temporary connectivity problems

The server handles these gracefully and provides clear error messages to help diagnose issues.

Disabling Tools

If you don't need all 17 tools, you can disable specific ones to reduce functionality or improve startup performance. This is useful for:

  • Reducing API surface: Limit available tools for security
  • Performance optimization: Faster startup with fewer tools
  • Specialized use cases: Only enable tools relevant to your workflow

You can disable tools using environment variables or command-line flags:

# Disable security-related tools
export WHOISXMLAPI_DISABLED_TOOLS="threat_intelligence,reverse_whois"

# Disable historical analysis tools
export WHOISXMLAPI_DISABLED_TOOLS="whois_history,dns_history"

See Configuration for complete documentation and examples.

Last Updated: