whois-mcp-server

---

概述

通过 RDAP 和 DNS-over-HTTPS 提供域名与网络情报。查询域名注册信息、检查注册局记录状态、获取 DNS 记录，并将 IP 和 ASN 解析到其注册局。无需 API 密钥。

工具

工具	描述
whois_lookup_domain	完整的域名注册记录——注册商、创建／到期日期、名称服务器、EPP 状态、DNSSEC、注册人组织
whois_check_availability	检查注册局记录是否存在；记录缺失并不能证明域名具备注册资格
whois_get_dns	通过 DNS-over-HTTPS 获取 DNS 所有者记录（A、AAAA、MX、TXT、NS、CNAME、SOA、CAA、PTR）
whois_lookup_ip	通过 RIR RDAP 查询 IP 或 CIDR 网段、组织、国家／地区、滥用联系信息及反向 DNS
whois_lookup_asn	将 ASN 解析为组织名称、国家／地区和 RIR 来源
whois_get_dossier	一次调用完成域名初步检查——并行获取注册信息和 DNS，并将结果规范化为包含事实性信号的单条记录

---

功能参考

whois_lookup_domain _工具

• 接受完全限定域名，并通过 IANA bootstrap 选择注册局的 RDAP 服务。
• 返回注册商、日期、名称服务器、EPP 状态、DNSSEC 和 registrant_redacted；如果注册局未提供证据，DNSSEC 和隐私状态将保持为 null。失败时会返回 rdap_no_coverage、domain_not_found 或 rdap_invalid_domain_response（响应与查询的域名不匹配）。
• 设置 include_registrar: true 会跟进一次注册商 RDAP 转介，并添加 registrar_detail（状态为 found、no_referral 或 failed，并附来源 URL）。默认关闭；受 RDAP_TIMEOUT_MS 限制，失败时仍会保留注册局结果。

---

whois_check_availability _工具

• 接受一个完全限定域名。
• 返回 registration_status: registered | not_found | unknown。对于已找到的注册，available 为 false；否则为 null，绝不会为 true：404 表示没有记录，并不代表该名称可以注册。
• 已知的 ICANN 子域名会返回 non_registrable_domain，并附上其可注册的父域名。

---

whois_get_dns _工具

• 接受一个 ASCII DNS 名称（允许使用 _dmarc.example.com 这类带下划线的标签），最长 253 个字符，标签长度为 1–63 个字符。可选的 types：A、AAAA、MX、TXT、NS、CNAME、SOA、CAA、PTR；默认值为 A、AAAA、MX、TXT、NS。
• 返回包含 TTL 和 query_sources: [{type, source}] 的记录，其中包括空响应和 NXDOMAIN。只要有任何查询获得成功的 Cloudflare 响应，旧版 source 就为 cloudflare，否则为 nextdns。
• 解析器失败代码和截断的响应会在重试并回退后返回错误。CAA 查询会发送到 NextDNS。

---

whois_lookup_ip _工具

• 接受带可选 CIDR 前缀的 IPv4/IPv6 地址（0–32 / 0–128）。原样回显 ip。
• 返回组织、国家/地区、滥用联系信息、提供商 CIDR（位于 cidrs 中；仅当恰有一个时才包含 cidr），以及尽力执行的反向 DNS 查询：ptr_status: found | not_found | failed；失败时会返回 ptr_source_error，同时保留 RDAP 数据。
• include_routing: true 会添加 routing（found | not_found | failed），其中包含 RIS 观测到的前缀和 origin_asns，数据来自 RIPEstat Network Info。默认关闭；路由查询失败时会保留 RDAP 和 PTR 结果。
• 以下情况会失败：invalid_ip、ip_not_found、ip_no_rdap_route（没有 RIR 覆盖该地址；不可重试），或者地址属于 0.0.0.0/8、10.0.0.0/8、100.64.0.0/10、127.0.0.0/8、169.254.0.0/16、172.16.0.0/12、192.168.0.0/16、255.0.0.0/8、::1/128、fc00::/7 或 fe80::/10 这些范围之一而导致的 private_range。

---

whois_lookup_asn _工具

• 接受范围为 1 到 4294967295 的 ASN，可带可选的 AS 前缀（例如 AS15169、AS 15169、+15169）。超出范围的数字会因 invalid_asn 而失败。
• 返回 name、org_name、country、rir、start_autnum 和 end_autnum；没有记录时会因 asn_not_found 而失败。

---

whois_get_dossier _工具

• 接受一个完全限定域名，并行执行注册信息以及 A/MX/NS/TXT 查询。
• 返回注册信息、DNS、域名年龄、隐私状态，以及推断出的 NS/MX 提供商。某项查询失败时，会保留另一项的数据，并设置 rdap_source_error 或 dns_source_error；both_legs_failed 表示两项查询均未成功。
• 空 MX（0 .）表示该域名不接收邮件。

---

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志。

RDAP / DNS 专属功能：

• 基于 HTTPS 的 RDAP — 不依赖 43 端口 TCP
• 自动选择 IANA 引导服务器 — 根据 TLD、RIR 或 ASN 范围选择正确的注册局 RDAP 服务；引导 JSON 会在内存中缓存 24 小时
• 通过 Cloudflare 和 NextDNS 提供 DNS-over-HTTPS — 双服务商按类型路由（CAA 使用 NextDNS；其他类型均使用 Cloudflare），并自动回退
• 无需 API 密钥 — 所有数据源（IANA、注册局 RDAP 端点、RIR RDAP、Cloudflare DoH、NextDNS DoH、可选的 RIPEstat Network Info）均为公开且无需密钥

适合 Agent 的输出：

• 通过两种方式指示覆盖情况 — whois_check_availability 和 whois_get_dossier 会以数据形式返回 rdap_coverage: false；同一情况下，whois_lookup_domain 会抛出 rdap_no_coverage
• 注册局有隐私脱敏迹象时，隐私脱敏字段为 true；没有证据时为 null
• 部分失败模型 — whois_get_dossier 会在查询失败时标记 source_error 字段并继续；只有两项查询都失败时才会报错
• 提供事实信号，而非评分 — age_days、privacy_redacted、ns_provider、mx_provider 均为真实数据，而非合成的风险评分

---

快速开始

无需 API 密钥或账户。将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "whois-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/whois-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "whois-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/whois-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "whois-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/whois-mcp-server:latest"
      ]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — 所有数据源均为公开数据。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/whois-mcp-server.git

2. 进入目录：

cd whois-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# All vars are optional — defaults work for most use cases

---

配置

变量	描述	默认值
RDAP_TIMEOUT_MS	RDAP 请求的 HTTP 超时时间，单位为毫秒。	5000
DOH_TIMEOUT_MS	DNS-over-HTTPS 请求的 HTTP 超时时间，单位为毫秒。	3000
RDAP_MAX_RETRIES	RDAP 暂时性故障时的最大重试次数。	2
DOH_MAX_RETRIES	DoH 暂时性故障时的最大重试次数。	2
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 监测。	false

完整的可选覆盖项列表请参见 .env.example。

---

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t whois-mcp-server .
docker run --rm -p 3010:3010 whois-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/whois-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

路径	用途
src/index.ts	入口点 — 启动应用。
src/app.ts	createApp() 选项 — 注册工具、初始化服务、声明会话模式。
src/config/	解析和验证特定于服务的环境变量（Zod）。
src/services/rdap/	RDAP 客户端 — IANA 引导缓存、域名/IP/ASN 查询、重试。
src/services/doh/	DNS-over-HTTPS 客户端 — 主要使用 Cloudflare，备用使用 NextDNS。
src/services/routing/	可选的 RIPEstat RIS 路由观测，使用有界交换。
src/mcp-server/tools/	工具定义（*.tool.ts）。
tests/	与 src/ 结构对应的 Vitest 测试。
docs/	设计和 API 参考文档。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录
• 通过 src/app.ts 的 tools 数组注册新工具
• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。