Whois MCP Server Domain IP ASN TLD Lookup

Overview

This project provides a lightweight MCP (Model Context Protocol) server that exposes whois-style lookups for domains, IPs, ASNs and TLDs. It’s designed to be used as a programmatic tool for enrichment, triage and automated workflows — for example, feeding registration and network ownership details into security playbooks, asset inventories, or LLM-based agents that use tool calls.

The server accepts HTTP requests and returns structured JSON responses for standard whois and RDAP queries. Because it implements a predictable tool-style interface, it can be run locally, containerized, or deployed behind an API gateway to serve as an on-demand data source for developer tools and automation pipelines.

Features

• Domain whois lookups (registration, registrar, dates, name servers)
• IP and ASN lookups (RDAP-style network and autonomous system metadata)
• TLD information and basic registry data
• Simple HTTP API with JSON responses for easy integration
• Lightweight Node.js server that can run locally or in Docker
• Optional caching and configurable timeouts for production use
• Useful for automated enrichment in SOC, incident response, and asset management

Installation / Configuration

Prerequisites: Node.js (16+) and npm, or Docker.

Clone and install locally:

git clone https://github.com/bharathvaj-ganesan/whois-mcp.git
cd whois-mcp
npm install

Copy the example environment file and adjust settings:

cp .env.example .env
# edit .env to set PORT, CACHE_TTL, etc.

Run in development:

npm run dev
# or
npm start

Run with Docker:

docker build -t whois-mcp .
docker run -p 3000:3000 --env-file .env whois-mcp

Common environment variables

Adjust these in your .env or container environment for production deployments.

Available Resources

The server exposes a small set of HTTP endpoints. All endpoints return JSON and use standard HTTP status codes.

Request format (example for domain):

POST /whois/domain
Content-Type: application/json

{
  "query": "example.com"
}

Successful response (trimmed example):

{
  "query": "example.com",
  "type": "domain",
  "registrar": "Example Registrar, Inc.",
  "created": "1995-08-14T00:00:00Z",
  "expires": "2027-08-13T23:59:59Z",
  "nameServers": ["a.iana-servers.net", "b.iana-servers.net"],
  "raw": "raw whois / registry data..."
}

IP lookup example:

POST /whois/ip
Content-Type: application/json

{ "query": "8.8.8.8" }

Response includes network range, assignment dates, and related organization/AS info.

Use Cases

• Security enrichment: Automatically attach registration and ASN details to alerts. Example: a SOC playbook calls /whois/ip for a suspicious IP and populates incident fields with the IP holder and ASN.
• Domain research: Investigators can query domain ownership, registrar and name servers to triage phishing or fraud reports. Example curl call shown above returns structured fields you can ingest into a case management system.
• Asset inventory: Periodic scans of known assets can call /whois/domain to detect impending domain expirations or ownership changes.
• LLM/Agent tooling: Use the server as an MCP-compatible tool endpoint that an LLM agent or orchestration layer can call to fetch factual registration and network context before generating responses or taking automated actions.
• Automation and CI: Integrate into CI checks for domain hygiene (e.g., verify nameserver configuration or expiry windows) as part of deployment pipelines.

Practical example — check a domain and print registrar and expiry:

curl -s -X POST http://localhost:3000/whois/domain \
  -H "Content-Type: application/json" \
  -d '{"query":"example.com"}' | jq '{registrar, created, expires}'

Notes and Best Practices

• Respect rate limits of upstream whois/RDAP services. Use the cache to reduce repeated lookups.
• Use timeouts and error handling in client code — reachable whois services may be slow or rate-limited.
• When deploying publicly, put the service behind an auth layer or API gateway to control usage and logging.

This server is intended as a practical, programmatic whois/RDAP tool for developer workflows and automation. Refer to the repository for code-level details, contributors, and licensing.