netdiag-mcp

English | 日本語

MCP server for on-demand network diagnostics — DNS lookups (with a DNSSEC AD-bit check), ping, an mtr-based path report, TCP port checks, HTTP status/redirect checks, TLS certificate inspection, and WHOIS, all from one server.

Built for triaging "can't reach X" / "is DNS propagated yet" reports without shelling into a jump host for each one-off dig/ping/curl.

Tools

All tools are read-only and single-target (no batch/sweep mode) — this is a convenience wrapper around checks an operator would run by hand, not a scanning tool. nmap-style multi-host/multi-port scanning is intentionally out of scope; deliberately probing many hosts or ports is a different, higher-blast-radius action that deserves its own tooling and approval flow.

tcp_port_check, http_check and tls_cert_check use Python's own socket/ssl/httpx stack rather than shelling out to nc/curl/openssl, so those three tools work even on a host with only the dig/ping/mtr/whois binaries installed (or none of them — health_check reports which are missing without failing the whole server).

dns_lookup/dnssec_check support DNS-over-TLS and DNS-over-HTTPS via transport="dot"/"doh" (dig's +tls/+https). This needs dig from BIND 9.18+ — an older dig rejects the flag outright rather than silently falling back to plain DNS, so a stale binary fails loudly instead of giving a false sense of having checked over an encrypted transport.

tls_cert_check/http_check against a bare IP address can fail TLS handshake with a "handshake failure" or similar error on SNI-hosted / CDN-fronted origins (e.g. behind Cloudflare) — TLS's SNI extension only carries hostnames, so an IP literal can't route to the right certificate on a shared edge. This is normal TLS behavior, not a tool bug; check by hostname when the target is CDN-fronted.

Setup

1. System dependencies

dns_lookup, dnssec_check, ping_host, traceroute_path and whois_lookup shell out to dig, ping, mtr and whois respectively. Install whichever of these you want available:

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

mtr needs raw-socket access. Debian/Ubuntu's mtr-tiny package grants cap_net_raw to the mtr-packet helper at install time, so it normally works for an unprivileged service user without further setup — verify with getcap "$(command -v mtr-packet)" if traceroute_path reports a socket permission error. Without that capability, traceroute_path fails cleanly with a ToolError rather than crashing the server.

2. Install

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

3. Claude Code (manual)

claude mcp add netdiag -- netdiag-mcp

No environment variables are required.

CLI

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

Security notes

• Every external-binary call passes an argv list (never a shell string), so no tool argument can break out into shell syntax.

• Hostname/IP and port arguments are validated and size/range-clamped before use — tool input is model-driven and treated as untrusted, the same as any other tool-calling surface.

• tcp_port_check connects to exactly one host:port per call; there is no loop or range argument, by design.

Development

Live smoke test

Unit tests check logic against fixtures; they cannot tell you that a tool has stopped returning real data (a dead dig/ping/mtr/whois binary, a broken TLS trust store, a network that blocks outbound ICMP). scripts/ smoke_test.py runs every registered tool against real public endpoints and fails on empty, malformed or error answers:

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

• No inventory, so every target is a fixed public endpoint — Cloudflare's 1.1.1.1 and IANA's example.com (reserved for documentation/testing use, RFC 2606). This server takes no config and has nothing to discover a target from, unlike a device-fleet MCP server in this family.

• tests/test_smoke_probes.py is the offline half: it only checks that every registered tool has a probe spec (and vice versa), so CI catches a tool added without deciding how anyone would know it works, without needing network access.

License

MIT