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 (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

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

The plugin launches uvx netdiag-mcp. No environment variables are required — the only prerequisite is the system dependencies above, and the TCP, HTTP and TLS checks work even without them.

uvx must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

4. 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