netdiag MCP

netdiag-mcp

English | 日本語

用于按需执行网络诊断的 MCP 服务——可从同一服务执行 DNS 查询（包括 DNSSEC AD 位检查）、ping、基于 mtr 的路径报告、TCP 端口检查、HTTP 状态码/重定向检查、TLS 证书检查和 WHOIS 查询。

专为快速排查“无法访问 X”／“DNS 是否已传播”的报告而构建，无需每次临时执行 dig／ping／curl 时都登录跳板机。

工具

工具	用途
dns_lookup	通过 dig 解析 DNS 记录（A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA），可选指定解析器，并可通过普通 DNS/DoT/DoH 查询
dnssec_check	查询已知会执行验证的解析器，并报告是否设置了 AD 位（普通 DNS/DoT/DoH）——这是确认 DNSSEC 验证情况的唯一可靠方法，因为普通 dig 回复中存在 RRSIG 本身并不能证明任何验证确实发生了
ping_host	ICMP ping（次数限制在 1 到 10 次）
traceroute_path	通过 mtr --report 生成逐跳路径/丢包报告（固定次数，并非实时／持续运行）
tcp_port_check	检查 TCP 端口是否开放——只执行普通套接字连接，不进行端口扫描
http_check	对 URL 执行 HEAD/GET，并报告状态码、重定向链和延迟
http_get	对 URL 执行 GET 并返回正文。仅支持文本类型（text/*、JSON、XML、JavaScript、YAML、+json/+xml），正文上限为 1 MiB。拒绝访问环回、链路本地和云元数据目标，包括通过重定向访问的情况
tls_cert_check	获取主机提供的证书，并报告主题／颁发者／有效期／SAN
whois_lookup	查询域名的 WHOIS 信息
asn_lookup	通过 Team Cymru 的 whois 服务查询 IP 的 ASN 和国家／地区代码，或查询 AS 编号的组织信息——无需 API 密钥或 GeoIP 数据库
current_time	获取 IANA 时区中的当前日期、时间和星期几——星期几作为数据返回，因为根据日期推算星期几涉及运算，可能静默出错。也会报告 UTC 时间和 epoch，因此还可用作时钟检查
health_check	版本信息，以及 PATH 中是否存在所包装的二进制文件（dig/ping/mtr/`whois）

所有工具均为只读且一次仅针对一个目标（不支持批量／扫描模式）——它们只是方便操作人员执行手动检查的封装工具，并非扫描工具。故意不支持 nmap 式的多主机／多端口扫描；有意探测大量主机或端口属于影响范围更广的操作，应使用专门工具并经过审批流程。

tcp_port_check、http_check、http_get 和 tls_cert_check 使用 Python 自带的 socket/ssl/httpx 技术栈，而非通过 shell 调用 nc/curl/openssl，因此即使主机只安装了 dig/ping/mtr/whois 二进制文件（甚至一个都没有），这四个工具也能正常工作（health_check 会报告缺少哪些二进制文件，但不会因此导致整个服务失败）。

dns_lookup/dnssec_check 支持通过 transport="dot"/"doh" 使用 DNS-over-TLS 和 DNS-over-HTTPS（对应 dig 的 +tls/+https）。这需要 BIND 9.18+ 的 dig——较旧的 dig 会直接拒绝该标志，而不是静默回退到普通 DNS，因此过时的二进制文件会明确报错，不会让人误以为已通过加密传输完成检查。

对纯 IP 地址执行 tls_cert_check/http_check 时，在使用 SNI 的主机／由 CDN 提供服务的源站（例如位于 Cloudflare 之后）上，TLS 握手可能会因“handshake failure”或类似错误而失败——TLS 的 SNI 扩展只携带主机名，因此 IP 地址无法在共享边缘节点上路由到正确的证书。这属于正常的 TLS 行为，并非工具错误；如果目标由 CDN 提供服务，请使用主机名进行检查。

设置

1. 系统依赖项

dns_lookup、dnssec_check、ping_host、traceroute_path 和 whois_lookup 分别会调用 dig、ping、mtr 和 whois。安装你希望使用的工具：

# Debian/Ubuntu
sudo apt install dnsutils iputils-ping mtr-tiny whois

mtr 需要原始套接字访问权限。Debian/Ubuntu 的 mtr-tiny 软件包会在安装时为 mtr-packet 辅助程序授予 cap_net_raw，因此通常无需进一步设置，即可由非特权服务用户正常使用。如果 traceroute_path 报告套接字权限错误，请使用 getcap "$(command -v mtr-packet)" 验证。若没有此权限，traceroute_path 会正常失败并返回 ToolError，而不会导致服务崩溃。

2. 安装

pip install netdiag-mcp
# or
uv tool install netdiag-mcp

3. Claude Code（插件）

此仓库同时也是一个仅包含单个插件的市场，因此 Claude Code 可以为你安装该服务：

/plugin marketplace add shigechika/netdiag-mcp
/plugin install netdiag-mcp@netdiag-mcp

该插件会启动 uvx netdiag-mcp。无需设置环境变量——唯一的前提是安装上述系统依赖项；即使没有这些依赖项，TCP、HTTP 和 TLS 检查仍可正常工作。

运行 Claude Code 的进程必须能在 PATH 中找到 uvx——登录 shell 通常可以，但通过 GUI 启动的应用可能不行；如果插件无法启动，请在系统范围内安装 uv。

4. Claude Code（手动）

claude mcp add netdiag -- netdiag-mcp

无需设置环境变量。

5. Codex

codex mcp add netdiag -- netdiag-mcp

其他任何能启动 stdio 服务的 MCP 客户端也可以用同样的方式运行：将 netdiag-mcp 指定为命令。

可选：http_get 的凭据

http_get 可以向配置的 https 前缀下的 URL 发送 Authorization 标头，以便读取受保护的 JSON 端点，而无需将凭据交给模型。将 NETDIAG_HTTP_AUTH 设置为一个 JSON 对象，用于将前缀映射到标头值：

NETDIAG_HTTP_AUTH='{"https://reports.example.ac.jp/daily/": "Bearer <token>"}'

• 每次请求和每次重定向跳转都会根据解析后的 URL 选择标头（仅限 https，主机和端口必须完全匹配，路径前缀必须位于 / 边界上）。重定向到其他位置时会移除该标头，以及随标头发送的任何 Cookie。 user@host 格式的 URL 永远不会匹配；路径中也不能包含字母、数字、.、_、~、- 和 / 以外的字符（不允许 %、; 或 ./.. 路径段），因此服务器无法通过规范化匹配的 URL 使其超出前缀范围。匹配到多个前缀时，选择最长的前缀；仅大小写、:443 或末尾的点不同的两个前缀会被判定为重复并拒绝。值必须是可打印的 ASCII 字符。
• netdiag-mcp 绝不会在自身的输出、错误或 health_check 中写入该值；结果的状态行会在最终跳转时携带该值的情况下显示 auth=applied，而 health_check 会以规范形式列出已配置的前缀（不包含值）。错误会按位置指出无效前缀，而不会显示其文本。前缀下的响应正文中，该值及其令牌部分会被替换为 [redacted]；但如果端点对其进行转换（例如使用 base64），仍可能泄露该值，因此前缀只能指向你控制的端点。
• 值格式错误时会明确报错：http_get 会返回错误，health_check 会报告 degraded。
• 该值只会从环境变量中读取。如果以同一用户身份运行多个实例（例如，一个向许多用户开放，另一个受到限制），请只在需要发送该值的实例的环境中设置它——配置文件会由所有实例共享。

CLI

netdiag-mcp --version   # print version
netdiag-mcp --check     # report missing binaries and a malformed NETDIAG_HTTP_AUTH (exit 0 when all binaries are present and the setting, if any, parses)

安全注意事项

• 每次调用外部二进制文件时都会传递 argv 列表（绝不传递 shell 字符串），因此任何工具参数都无法逃逸并执行 shell 语法。
• 使用前会验证主机名/IP 和端口参数，并限制其大小和范围——工具输入由模型生成，会被视为不可信输入，与其他任何工具调用接口一样。
• tcp_port_check 每次调用只连接到一个主机:端口；按设计，它不接受循环或范围参数。
• 可选的 http_get 凭据绝不会离开配置的 https 前缀，netdiag-mcp 也绝不会打印该凭据；如果响应正文回显了凭据，这是服务器造成的（见上文）。

开发

实时冒烟测试

单元测试会根据固定样例检查逻辑；但它们无法告诉你某个工具是否已停止返回真实数据（dig/ping/mtr/whois 二进制文件失效、TLS 信任存储损坏，或网络阻止了出站 ICMP）。scripts/ smoke_test.py 会针对真实公共端点运行所有已注册工具，并在结果为空、格式错误或包含错误时失败：

uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only ping --traceback

• 没有设备清单，因此每个目标都是固定的公共端点——Cloudflare 的 1.1.1.1 和 IANA 的 example.com（根据 RFC 2606 保留用于文档/测试）。 与此系列中的设备群 MCP 服务不同，此服务不接受任何配置，也没有可用于发现目标的信息。
• tests/test_smoke_probes.py 是离线部分：它只检查每个已注册工具是否都有探测规格（反之亦然），因此 CI 会发现新增工具却未确定如何验证其是否正常工作的情况，而且无需访问网络。

许可证

MIT