whois-mcp

simplebytes-com/whois-mcp

3.2

If you are the rightful owner of whois-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A simple Model Context Protocol (MCP) server that provides WHOIS domain lookup capabilities using IANA's WHOIS service.

Tools
1
Resources
0
Prompts
0

WHOIS MCP Server

A Model Context Protocol (MCP) server that provides comprehensive WHOIS domain lookup using the proper WHOIS protocol (TCP port 43). Queries authoritative WHOIS servers directly with support for 877+ TLDs and parsing for 169 country-code TLDs.

Features

  • Native WHOIS Protocol: Direct TCP port 43 connections to authoritative WHOIS servers
  • 877+ TLDs Supported: Comprehensive dictionary of WHOIS servers for all major TLDs
  • 169 ccTLD Parsers: Format-specific parsing for country-code TLDs (.gg, .pl, .jp, .kr, .ru, .de, .it, etc.)
  • Auto-Update: Refresh WHOIS server dictionary from IANA with built-in tool
  • Comprehensive Parsing: Extracts registrar, dates, nameservers, status, DNSSEC, contacts
  • Lightweight: Single-file executable, minimal dependencies
  • Easy Integration: Works with Claude Desktop and any MCP-compatible client

Installation

npm install whois-mcp

Or use directly with npx:

npx whois-mcp

Usage

Option 1: Local Installation (Recommended for Claude Desktop)

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whois": {
      "command": "npx",
      "args": ["-y", "whois-mcp"]
    }
  }
}

Restart Claude Desktop, and you'll see the WHOIS tools in the 🔌 menu.

Option 2: Hosted Version

This server is also available as a hosted service at mcp.domaindetails.com for HTTP-based integrations.

Available Tools

whois_lookup

Look up domain registration information using the proper WHOIS protocol (port 43).

Parameters:

  • domain (string, required): Domain name to look up (e.g., google.com, theo.gg, mineo.pl)
  • include_raw (boolean, optional): Include raw WHOIS response data (default: false)

Example Request:

{
  "domain": "theo.gg",
  "include_raw": false
}

Example Response:

{
  "domain": "theo.gg",
  "found": true,
  "method": "whois",
  "server": "whois.gg",
  "timestamp": "2025-10-30T11:11:32.936Z",
  "registrar": "NameCheap, Inc (https://www.namecheap.com)",
  "registrant": "Redacted for privacy",
  "creationDate": "2021-01-14T00:00:00Z",
  "expirationDate": "2026-01-14T00:00:00Z",
  "nameservers": [
    "dns1.registrar-servers.com",
    "dns2.registrar-servers.com"
  ],
  "status": [
    "Active",
    "Transfer Prohibited by Registrar"
  ],
  "parsed": {
    "domainName": "theo.gg",
    "registrar": "NameCheap, Inc (https://www.namecheap.com)",
    "creationDate": "2021-01-14T00:00:00Z",
    "expirationDate": "2026-01-14T00:00:00Z",
    "nameservers": ["dns1.registrar-servers.com", "dns2.registrar-servers.com"],
    "registrant": "Redacted for privacy",
    "status": ["Active", "Transfer Prohibited by Registrar"],
    "dnssec": null,
    "lastModified": null
  }
}

list_supported_tlds

List all TLDs that have WHOIS servers available for querying.

Parameters:

  • limit (number, optional): Maximum number of TLDs to return (default: all)

Example Response:

{
  "totalCount": 877,
  "returnedCount": 10,
  "tlds": [
    "aaa",
    "aarp",
    "abarth",
    "abb",
    "abbott",
    "abbvie",
    "abc",
    "able",
    "abogado",
    "abudhabi"
  ],
  "timestamp": "2025-10-30T11:11:32.936Z"
}

refresh_whois_servers

Refresh the WHOIS server dictionary by fetching the latest TLD list from IANA. Run this periodically to ensure the server list is up-to-date with new TLDs.

Example Response:

{
  "success": true,
  "message": "WHOIS server dictionary refreshed successfully",
  "previousCount": 877,
  "currentCount": 880,
  "added": 3,
  "timestamp": "2025-10-30T11:11:32.936Z",
  "output": "Sync complete! Updated whois_dict.json"
}

WHOIS Data

The server queries authoritative WHOIS servers via TCP port 43 and parses responses to extract:

  • Domain Name: Canonical domain name
  • Registrar: Domain registrar/registry information
  • Registration Dates: Creation, expiration, and last modified dates
  • Registrant: Domain owner information (when available, may be redacted for privacy)
  • Admin Contact: Administrative contact (when available)
  • Tech Contact: Technical contact (when available)
  • Nameservers: DNS nameservers for the domain
  • Status: Domain status codes (active, transfer prohibited, etc.)
  • DNSSEC: DNSSEC signing status

Supported TLDs

The server includes a comprehensive dictionary (whois_dict.json) with WHOIS servers for:

  • Generic TLDs: .com, .net, .org, .info, .biz, etc.
  • Country-code TLDs: 169 ccTLDs with format-specific parsers (.gg, .pl, .jp, .kr, .ru, .de, .it, .fr, .uk, .au, .nz, .ca, etc.)
  • New gTLDs: .app, .dev, .ai, .io, .me, .ly, and hundreds more

Parser Features

The included WHOIS parser supports diverse response formats:

  • Standard formats: Colon-separated key-value pairs
  • .gg/.je style: Natural language dates ("30th April 2003")
  • .jp style: Square bracket format [Domain Name] GOOGLE.JP
  • .kr style: Dotted dates 2007. 03. 02.
  • .ru style: Cyrillic fields with IP addresses
  • Multi-line sections: Status blocks, nameserver lists, contact blocks

Technical Details

Architecture

  • Protocol: Native WHOIS (TCP port 43) via Node.js net module
  • Parser: Based on whois-parser with 169 ccTLD parsers
  • Dictionary: whois_dict.json with 877+ WHOIS server mappings
  • Update Script: fetch-iana-servers.js syncs latest TLDs from IANA
  • Build: Single-file executable via esbuild

Attribution

This MCP server uses the comprehensive WHOIS parser from:

The parser includes support for 169 country-code TLDs with format-specific parsing logic.

Development

# Clone repository
git clone https://github.com/simplebytes-com/whois-mcp.git
cd whois-mcp

# Install dependencies
npm install

# Build
npm run build

# Test locally
node build/index.js

# Test with specific domains
node test-simple.js

Build Process

The build script:

  1. Bundles source files with esbuild
  2. Adds shebang for CLI execution
  3. Copies whois_dict.json and fetch-iana-servers.js to build directory
  4. Makes the executable file

Updating the WHOIS Dictionary

The WHOIS server dictionary can be updated from IANA:

cd src
node fetch-iana-servers.js

This fetches the latest TLD list from https://data.iana.org/TLD/tlds-alpha-by-domain.txt and updates whois_dict.json with current WHOIS servers.

Examples

Example 1: .com Domain (google.com)

{
  "domain": "google.com",
  "found": true,
  "server": "whois.verisign-grs.com",
  "registrar": "MarkMonitor Inc.",
  "creationDate": "1997-09-15T04:00:00Z",
  "expirationDate": "2028-09-14T04:00:00Z",
  "nameservers": ["NS1.GOOGLE.COM", "NS2.GOOGLE.COM", "NS3.GOOGLE.COM", "NS4.GOOGLE.COM"],
  "status": ["clientDeleteProhibited", "clientTransferProhibited", "clientUpdateProhibited"],
  "dnssec": "unsigned"
}

Example 2: .gg ccTLD (theo.gg)

{
  "domain": "theo.gg",
  "found": true,
  "server": "whois.gg",
  "registrar": "NameCheap, Inc",
  "registrant": "Redacted for privacy",
  "creationDate": "2021-01-14T00:00:00Z",
  "expirationDate": "2026-01-14T00:00:00Z",
  "nameservers": ["dns1.registrar-servers.com", "dns2.registrar-servers.com"],
  "status": ["Active", "Transfer Prohibited by Registrar"]
}

Example 3: .pl ccTLD (mineo.pl)

{
  "domain": "mineo.pl",
  "found": true,
  "server": "whois.dns.pl",
  "registrar": "Dynadot LLC",
  "creationDate": "2021.02.18 23:49:54",
  "expirationDate": "2027.02.18 23:49:54",
  "nameservers": ["josephine.ns.cloudflare.com", "kenneth.ns.cloudflare.com"],
  "dnssec": "Unsigned",
  "lastModified": "2024.09.03 13:16:45"
}

Troubleshooting

No WHOIS Server Found

If you get "No WHOIS server found for TLD", try refreshing the dictionary:

Use the refresh_whois_servers tool to update from IANA

Connection Timeout

Some WHOIS servers have rate limiting. Wait a few seconds and retry. The default timeout is 30 seconds.

Parsing Issues

The parser supports 169 ccTLDs, but some registries use unique formats. The raw WHOIS data is always available with include_raw: true.

License

MIT

Related Projects

Support