Look up domain registration, check availability, fetch DNS records, and resolve IPs and ASNs via RDAP and DNS-over-HTTPS via MCP. STDIO or Streamable HTTP.\n
\n\n[](https://github.com/cyanheads/whois-mcp-server/releases/latest/download/whois-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=whois-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvd2hvaXMtbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22whois-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fwhois-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nSix tools covering domain intelligence, DNS, and IP/ASN resolution:\n\n| Tool | Description |\n|:-----|:------------|\n| `whois_lookup_domain` | Full domain registration record — registrar, created/expiry dates, nameservers, EPP status, DNSSEC, registrant org |\n| `whois_check_availability` | Check whether a domain is registered or available for registration |\n| `whois_get_dns` | DNS records for any hostname via DNS-over-HTTPS (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR) |\n| `whois_lookup_ip` | IP or CIDR netblock, org, country, abuse contact, and reverse DNS via RIR RDAP |\n| `whois_lookup_asn` | Resolve an ASN to its org name, country, and RIR source |\n| `whois_get_dossier` | One-call domain triage — registration + DNS in parallel, normalized into a single record with factual signals |\n\n### `whois_lookup_domain`\n\nLook up a domain's full RDAP registration record.\n\n- RDAP-first via IANA auto-bootstrap — automatically selects the correct registry RDAP server per TLD\n- Returns registrar, creation/expiry dates, nameservers, EPP status codes, DNSSEC delegation flag\n- Surfaces `registrant_redacted: true` explicitly when privacy redaction is in effect (standard post-GDPR for gTLDs)\n- Returns `rdap_coverage: false` for TLDs without RDAP coverage rather than silently failing\n- Includes `last_update_of_rdap_db` event timestamp for data freshness transparency\n\n---\n\n### `whois_check_availability`\n\nCheck whether a domain name is registered or available to register.\n\n- RDAP 404 = available (`available: true`) — exploits the RDAP spec's intended behavior\n- Returns `available: false` with `registrar` and `expiry_date` when registered\n- Returns `available: null` with `rdap_coverage: false` for TLDs without RDAP — cannot determine availability\n- Optimized for bulk name sweeps — thin response, no unnecessary fields\n\n---\n\n### `whois_get_dns`\n\nFetch DNS records via DNS-over-HTTPS.\n\n- Cloudflare primary, NextDNS fallback (CAA records always use NextDNS — Cloudflare returns raw hex wire format for them)\n- Supports A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR — multiple types in one call\n- Returns records with TTLs and the resolving source (`cloudflare` or `nextdns`)\n- `nxdomain: true` in result (not an error) when the domain doesn't exist in DNS\n\n---\n\n### `whois_lookup_ip`\n\nLook up an IP address or CIDR block via RIR RDAP.\n\n- Auto-routes to the correct RIR (ARIN, RIPE, APNIC, LACNIC, AFRINIC) via IANA IP bootstrap\n- Returns netblock CIDR, org name, country, abuse contact email\n- Fetches PTR (reverse DNS) via DoH as a best-effort step — `ptr: null` on failure, not an error\n- Validates and rejects private/reserved ranges (RFC 1918, loopback, link-local) with a clear error\n\n---\n\n### `whois_lookup_asn`\n\nResolve an ASN to its org name, country, and RIR.\n\n- Accepts `AS15169` or bare integer `15169` format\n- Routes to the correct RIR RDAP endpoint via IANA ASN bootstrap\n- Returns `name`, `org`, `country`, `rir`, `start_autnum`, `end_autnum`\n\n---\n\n### `whois_get_dossier`\n\nOne-call domain triage aggregating registration and DNS data in parallel.\n\n- Runs RDAP domain lookup and DoH (A, MX, NS, TXT) in parallel via `Promise.allSettled`\n- Inferred signals: `age_days`, `privacy_redacted`, `registrar`, `ns_provider` (from NS records), `mx_provider` (from MX records)\n- No synthesized risk scores — factual signals only; the agent decides the verdict\n- Partial results surfaced when one leg fails (`source_error` on the failed leg)\n- Both-legs-fail throws `ServiceUnavailable`; individual leg failures are data, not errors\n\n---\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nDomain and network intelligence:\n\n- RDAP over HTTPS — no port-43 TCP dependency, runs on Node, Bun, and Cloudflare Workers\n- IANA bootstrap auto-selection — correct registry RDAP server picked per TLD, RIR, or ASN range; bootstrap JSON cached (TTL 24h) in tenant state\n- DNS-over-HTTPS via Cloudflare and NextDNS — resilient dual-provider with per-type routing (NextDNS for CAA; Cloudflare for all others)\n- No API keys required — all sources (IANA, registry RDAP endpoints, RIR RDAP, Cloudflare DoH, NextDNS DoH) are public and keyless\n\nAgent-friendly output:\n\n- Explicit coverage signals — `rdap_coverage: false` tells the agent the TLD lacks RDAP rather than returning a confusing error\n- Privacy redaction surfaced as a field — `registrant_redacted: true` rather than silently absent contact data\n- Partial failure model — `whois_get_dossier` marks individual legs with `source_error` and continues; only both-legs-fail escalates to an error\n- Factual signals, not scores — `age_days`, `privacy_redacted`, `ns_provider`, `mx_provider` are real data; agents chain into threat-intel or risk servers for enrichment\n\n---\n\n## Getting started\n\nNo API keys or accounts required. Add the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"whois-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/whois-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"whois-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/whois-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"whois-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/whois-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API keys required — all data sources are public.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/whois-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd whois-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# All vars are optional — defaults work for most use cases\n```\n\n---\n\n## Configuration\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `RDAP_TIMEOUT_MS` | HTTP timeout for RDAP requests in milliseconds. | `5000` |\n| `DOH_TIMEOUT_MS` | HTTP timeout for DNS-over-HTTPS requests in milliseconds. | `3000` |\n| `RDAP_MAX_RETRIES` | Max retry attempts on transient RDAP failures. | `2` |\n| `DOH_MAX_RETRIES` | Max retry attempts on transient DoH failures. | `2` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n---\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n bun run rebuild\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t whois-mcp-server .\ndocker run --rm -p 3010:3010 whois-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/whois-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n---\n\n## Project structure\n\n| Path | Purpose |\n|:-----|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |\n| `src/config/` | Server-specific environment variable parsing and validation (Zod). |\n| `src/services/rdap/` | RDAP client — IANA bootstrap cache, domain/IP/ASN lookup, retry. |\n| `src/services/doh/` | DNS-over-HTTPS client — Cloudflare primary, NextDNS fallback. |\n| `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`). |\n| `tests/` | Vitest tests mirroring `src/`. |\n| `docs/` | Design and API reference documents. |\n\n---\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage (IANA bootstrap cache)\n- Register new tools via `src/index.ts` tools array\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n---\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 11872,
"sha": "650ed57b9aecb95a16de3d9e8d5bda55017bead88c12904dc002981bd5830c20",
"repo_slug": "cyanheads/whois-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_whois_mcp_server_fcba7f3e/readme"
}