DNS MCP Server

DNS MCP 服务

通过 MCP 为 AI 助手提供实时 DNS 安全分析。让你的 助手能够像从业者一样调查域名——DNSSEC 链验证、电子邮件身份验证 状况和注册信息情报——无需离开聊天会话。

由网络安全专业人士为 SOC 调查工作流打造。 这不是玩具——你在命令行中运行的同样查询， 可通过任何兼容 MCP 的助手实时访问。

架构（2.0.0）

dns-mcp 是一个 Streamable HTTP MCP 服务，通过 Pocket ID 实现 OAuth。工具实现是对 dns_tool Python 库的轻量封装，所有 DNS 逻辑均由该库负责。服务本身约有 430 行代码：身份验证引导、 工具注册和提示词加载。

Claude.ai / Claude Code / any MCP client
              │
              │ Streamable HTTP + OAuth bearer (JWT)
              ▼
       Caddy reverse proxy           (TLS, DNS-01 / Let's Encrypt)
              │
              ▼
     dns-mcp container               (FastMCP, OAuth verifier)
              │
              ▼
        dns_tool library             (DoH client, validators, parsers)
              │
              ▼
   doh.lab.deflationhollow.net      (Unbound DoH resolver, optional)

相较于之前仅支持 stdio 的架构，具有三项优势：

1. 可通过网络访问 — 托管的 MCP 服务可以为任何客户端提供服务，而不仅仅是 能够启动本地子进程的客户端。
2. 受 OAuth 保护 — 根据 Pocket ID JWKS 验证 bearer JWT；工具可通过 whoami 获取每位用户的身份信息。
3. 以库为先 — dns_tool 独立发布且可重复使用。同一份代码支持 CLI、本 MCP 服务以及（最终推出的）REST API。

旧的 stdio 架构保留在 server.py.legacy 中，供移植时参考。 remote 分支（mcp-shim Go 桥接程序）已弃用。

工具

dns-mcp 2.0.0 目前提供 19 个工具。来自 1.x stdio 架构的另外十个工具尚待移植到 dns_tool 中——请参阅 待处理工作。

元信息

工具	描述
ping	服务运行时间、当前时间戳、dns_tool 版本 + 提交哈希
whoami	从 JWT 声明中获取已验证身份的用户信息

DNS

工具	描述
dns_query	通过 DoH 执行标准 DNS 查询 — 20 种记录类型（A、AAAA、MX、TXT、NS、SOA、CNAME、PTR、SRV、CAA、DNSKEY、DS、RRSIG、NSEC、NSEC3、TLSA、SSHFP、HTTPS、SVCB、NAPTR）。可选的 subnet 会发送 EDNS Client Subnet 提示（RFC 7871）；ecs 区块会说明答案是否确实针对该提示进行了定制
dnssec_validate	从 IANA 根信任锚开始，向下遍历完整 DNSSEC 链。在每个区域切分点执行实际的加密验证。返回结构化的 verdict、各区域发现结果和事件记录
nsec_info	NSEC / NSEC3 不存在性证明分析 — 区域可遍历性评估、NSEC3 哈希参数、opt-out 检测

电子邮件安全

工具	描述
check_spf	解析 SPF 记录并递归解析 include（RFC 7208 的 10 次查询限制）
check_dmarc	获取 DMARC 策略，并回退到组织域名
check_dkim	验证指定选择器与域名对应的 DKIM 公钥记录
enumerate_dkim_selectors	使用已知选择器名称探测域名的 DKIM 密钥；返回成功解析的选择器
check_dane	查询域名所有 MX 主机的 DANE TLSA 记录
check_tlsa	独立查询 _<port>._<proto>.<host> 处的 TLSA 记录

威胁情报

工具	描述
check_rbl	使用 8 个基于 DNS 的 RBL 检查 IP 信誉（Spamhaus ZEN、SpamCop、UCEProtect L1/L2、Mailspike、PSBL、Barracuda、SORBS）
check_dbl	使用基于 DNS 的域名阻止列表检查域名信誉（Spamhaus DBL、URIBL、SURBL）
cymru_asn	通过 Team Cymru DNS 服务查询 ASN — BGP 前缀、组织、国家/地区
check_fast_flux	快速通量检测 — 重复查询 A/AAAA 记录，以识别轮换 IP 和短 TTL
detect_hijacking	测试递归解析器是否遭到篡改 — NXDOMAIN 通配符、DNSSEC 处理、身份

注册信息

工具	描述
rdap_lookup	通过 RDAP 查询域名注册数据（现代 WHOIS 替代方案）

可观测性

工具	描述
session_stats	当前进程中各工具的调用统计信息——调用次数、错误次数、平均耗时（毫秒）、最大耗时（毫秒）、首次/最近调用时间戳；以及会话运行时间和总调用次数。模块级状态（容器重启后重置）。由 dns_mcp/tracking.py 提供支持。
reset_stats	清除所有工具调用统计信息并重启会话计时器。

下游使用方（例如 ~/projects/yahoo 批量取证任务）会在每次调查中调用 session_stats 作为最后一个工具，以记录咨询过哪些 DNS 工具；空的统计字典表示“冷读”， 即分析员大模型在没有 DNS 验证的情况下给出了结论。

工具描述符

全部 19 个工具都使用 Pydantic Field 描述参数。大模型可以看到：

• 各参数的描述，说明参数的含义
• 用于记录类型和协议的 Literal[...] 枚举（无需猜测字符串）
• 用于验证 FQDN 语法、IPv4 点分四段格式和 DKIM 选择器格式的 正则表达式模式
• 长度和范围限制（端口为 1–65535，FQDN 最长 253 个字符，等等）

这些限制会公布在工具描述符 JSON Schema 中，并由 FastMCP 在 MCP 边界强制执行——无效输入会在调用 dns_tool 前被拒绝。类型别名定义请参阅 src/dns_mcp/server.py。

分析员提示词

服务器附带四个分析员提示词模板。任何兼容 MCP 且支持提示词的客户端都可以列出并调用这些模板。

提示词	功能
email_security_audit	SPF、DKIM、DMARC、MTA-STS、BIMI 审计——按 A 到 F 评级，并提供按优先级排序的建议
dnssec_chain_audit	从 IANA 根区到目标的完整 DNSSEC 信任链审计
soc_email_forensics	对原始邮件进行钓鱼取证分析——可判定为 TRUSTABLE / SUSPICIOUS / PHISHING / FURTHER ANALYSIS REQUIRED
nist_800_81r3_audit	根据 NIST SP 800-81r3 对域名安全态势进行审计

调用提示词需要客户端侧的 UI 支持。Claude Code 会将它们显示为 /mcp__dns-mcp__<prompt_name>。Claude.ai 网页版通过斜杠命令选择器提供提示词。不支持提示词的客户端可按需使用工具。

示例

向助手提问：“检查 example.com 的电子邮件安全态势”

助手依次调用 check_spf、check_dmarc、check_dane，并返回完整分析：

✅ SPF:     Hard fail (-all), 3 lookups (under RFC limit)
✅ DMARC:   p=reject, pct=100 — full enforcement, aggregate reporting configured
✅ DANE:    TLSA records present and DNSSEC-validated

无需复制粘贴 dig 命令。无需切换标签页。只需一个问题。

快速开始

先决条件

• Docker
• Pocket ID 实例（或支持动态客户端注册的任意 OIDC 提供商）
• 支持 TLS 终止的反向代理（Caddy、nginx 等）
• 指向反向代理的域名

1. Pocket ID

在 Pocket ID 的 UI 中生成管理员 API 密钥：Settings → API Keys → Create new key。将其命名为 dns-mcp，以便在需要时只撤销此服务的密钥。复制 密钥值（该值只会显示一次）。

2. .env

POCKET_ID_BASE_URL=https://pocketid.example.com
POCKET_ID_API_KEY=<the key from step 1>
SERVER_URL=https://dns-mcp.example.com

3. 部署

git clone https://github.com/mclose/dns-mcp.git
cd dns-mcp
docker compose up -d

该镜像会将 dns_tool 作为版本固定的依赖项安装（URL 固定在 pyproject.toml 中）；也可以使用 make build 直接进行开发。

4. 反向代理

容器监听端口 8000（HTTP）。在其前端配置 TLS 终止：

dns-mcp.example.com {
    reverse_proxy dns-mcp:8000 {
        flush_interval -1   # required for Streamable HTTP / SSE
    }
}

如果你使用 mclose/gateway（提供 dns-mcp.lab.deflationhollow.net 的 Caddy + DNS-01 配置），请添加符合现有模式的 conf.d/dns-mcp.conf。

5. 连接

在 MCP 客户端中添加 https://dns-mcp.example.com/mcp 作为连接器。首次连接时会运行一次 OAuth 流程——Claude.ai 会重定向到 Pocket ID，你完成身份验证后，服务器会在你的 Pocket ID 实例上创建一个 DCR 客户端， 并返回 JWT。后续工具调用会将该 JWT 作为 bearer token 发送；服务器会根据 Pocket ID JWKS 验证该令牌。

待完成工作

1.x 标准输入输出架构中的 11 个工具尚未移植到 dns_tool，因此未在 2.0.0 中注册：

• check_caa（包括 CNAME 链跟踪和通配符委派检测）
• check_zone_transfer（AXFR 枚举）
• check_bimi、check_mta_sts、check_smtp_tlsrpt
• check_ct_logs（通过 crt.sh 枚举证书透明度日志）
• timestamp_converter、reverse_dns
• enumerate_dkim_selectors、dns_dig_style、dns_query_dot

参考实现位于 server.py.legacy。每项移植工作都需要将函数移至相应的 dns_tool 模块（dns_tool.email、dns_tool.intel 等），在库端添加测试，并在 src/dns_mcp/server.py 中注册一个单行包装函数。

文件结构

dns-mcp/
├── src/dns_mcp/
│   ├── __init__.py
│   ├── __main__.py            # entrypoint — create_server().run(transport="streamable-http")
│   ├── config.py              # pydantic-settings Settings class
│   ├── auth.py                # JWKSTokenVerifier + JWTAccessToken
│   └── server.py              # FastMCP app: OAuth routes + 16 tools + 4 prompts (~430 lines)
├── prompts/                   # MCP analyst prompt text files
├── tests/                     # pytest unit tests (legacy — pending rewrite)
├── tools/                     # operator scripts (smoke tests, deploy helpers)
├── server.py.legacy           # 1.x stdio server (5,095 lines), reference for 11 deferred tool ports
├── compose.yaml
├── Dockerfile
├── pyproject.toml             # dns_tool URL-pinned to dist tarball
└── Makefile                   # build/lint/import-check

日常操作

命令	说明
make build	重新构建 Docker 镜像
make rebuild	完全清理后重新构建，不使用缓存
make lint	pre-commit run --all-files（ruff 检查 + 格式化）
make import-check	构建镜像，在其中运行 create_server()，并断言工具已注册
make shell	在容器内打开交互式 Shell
make deploy	推送到 GitHub + VPS post-receive 钩子
make logs	跟踪容器日志
make status	查看容器状态

安全性

• 不执行 Shell 命令——所有 DNS 查询都通过 dns_tool（内部使用 dnspython），RDAP 通过 requests 处理
• 每次调用工具时，都会根据 Pocket ID JWKS 验证 OAuth bearer JWT
• 在 MCP 边界强制执行 Pydantic Field 约束——无效输入会在到达 dns_tool 前 被拒绝
• 使用非 root 容器用户（claude，uid 1000）
• 强制执行 SPF 递归限制（RFC 7208）
• RDAP：超时时间为 10s，最多重定向 3 次

许可证

MIT