netdiag-mcp

English | 日本語

用于按需网络诊断的 MCP 服务器 — DNS 查询（带 DNSSEC AD 位检查）、ping、基于 mtr 的路径报告、TCP 端口检查、HTTP 状态/重定向检查、TLS 证书检查以及 WHOIS，全部集中在一台服务器上。

专为排查"无法访问 X"/"DNS 是否已传播"类报告而构建，无需为每次一次性的 dig/ping/curl 操作登录跳板机。

工具

所有工具均为只读且单目标（无批量/扫描模式）— 这是对运维人员手动执行的检查的便捷封装，而非扫描工具。nmap 风格的多主机/多端口扫描被有意排除在范围之外；故意探测大量主机或端口是另一种影响范围更大的操作，需要专门的工具和审批流程。

tcp_port_check、http_check 和 tls_cert_check 使用 Python 自带的 socket/ssl/httpx 栈，而不是调用 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 握手失败 — 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 mcp add netdiag -- netdiag-mcp

无需环境变量。

命令行界面

netdiag-mcp --version   # print version
netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)

安全说明

• 每次外部二进制调用都传递 argv 列表（绝不使用 shell 字符串），因此任何工具参数都无法逃逸为 shell 语法。

• 主机名/IP 和端口参数在使用前都会经过验证和大小/范围限制 — 工具输入由模型驱动，并被视为不受信任的数据，与任何其他工具调用面相同。

• tcp_port_check 每次调用仅连接一个 host:port；按照设计，没有循环或范围参数。

开发

实时冒烟测试

单元测试根据固定数据检查逻辑；它们无法告诉您某个工具是否已停止返回真实数据（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