io.github.shigechikaPublished by GitHub account shigechikav0.8.1Updated Oct 26, 2026
MCP server wrapping dig, ping, mtr, whois and TLS/HTTP checks for on-demand network diagnostics
Local MCP server that wraps dig, ping, mtr, whois and TLS/HTTP checks so an assistant can run one-off network diagnostics on demand.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
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.
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, http_get and tls_cert_check use Python's
own socket/ssl/httpx stack rather than shelling out to nc/curl/openssl,
so those four 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.
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:
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.
This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:
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.
No environment variables are required.
Any other MCP client that launches stdio servers works the same way: give it
netdiag-mcp as the command.
http_gethttp_get can send an Authorization header to URLs under a configured https
prefix, for reading a protected JSON endpoint without handing the credential to
the model. Set NETDIAG_HTTP_AUTH to a JSON object mapping prefix to header
value:
/ boundary). A
redirect to anywhere else drops it, along with any cookie set while it was
attached.
user@host URLs never match, and neither does a path with anything beyond
letters, digits, ., _, ~, - and / (no %, ; or ./..
segments), so a server cannot normalise a matched URL out of the prefix. The
longest matching prefix wins; two prefixes that differ only in case, :443 or
a trailing dot are rejected as duplicates. Values must be printable ASCII.health_check; the result's status line says auth=applied when the final
hop carried it, and health_check lists the configured prefixes in canonical
form (not the values). Errors name a bad prefix by position, not by text. A
response body under the prefix has the value (and its token part) masked as
[redacted], but an endpoint that transforms it (for example base64) would
still reveal it, so point a prefix only at endpoints you control.http_get returns an error and
health_check reports degraded.tcp_port_check connects to exactly one host:port per call; there is no
loop or range argument, by design.http_get credential never leaves the configured https prefix
and netdiag-mcp never prints it; a response body that echoes it is the
server's doing (see above).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:
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.MIT
Source: README.md at commit de70a6c
Service health: version, which wrapped binaries are present on PATH, and the http_get auth prefixes. Returns a fixed shape (status/service/version + backend fields) so a monitoring caller never has to branch on missing keys. status is "healthy" when every wrapped binary is found and NETDIAG_HTTP_AUTH (if set) parses, "degraded" otherwise (the affected tools fail at call time). http_auth lists the configured URL prefixes, never the header values.
Takes no parameters.
Resolve a DNS record via `dig`. record_type: A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA. Pass resolver to query a specific nameserver instead of the host default (e.g. to check whether a change has propagated to a given resolver). transport: "plain" (UDP/TCP 53, default), "dot" (DNS-over-TLS, 853) or "doh" (DNS-over-HTTPS, 443). Requires dig from BIND 9.18+; an older dig rejects dot/doh outright instead of silently querying over plain DNS.
hostnamerequiredresolvertransportrecord_typeCheck whether a name validates DNSSEC against a known-validating resolver (AD bit). transport: "plain" (default), "dot" or "doh" — compare validation over plain DNS vs. an encrypted transport when port 53 may be intercepted.
hostnamerequiredresolvertransportICMP ping a host or IP. count is clamped to 1-10.
hostrequiredcountPath/MTU-style hop report via `mtr --report` (fixed cycles, not a live run). cycles clamped 1-10.
hostrequiredcyclesCheck whether a TCP port is open (plain socket connect, no port scanning).
hostrequiredportrequiredtimeoutHEAD/GET a URL and report status, redirect chain and latency.
urlrequiredtimeoutGET a URL and return the response body (text/JSON/XML only, capped at max_bytes, hard cap 1 MiB). Use this to read a JSON endpoint or inspect an error page. For status/latency only, use http_check instead.
urlrequiredtimeoutmax_bytesFetch the TLS certificate presented on host:port and report subject/issuer/validity/SANs.
hostrequiredportWHOIS lookup for a domain.
domainrequiredASN + country-code lookup for an IP, or org info for an AS number (e.g. AS15169 or 15169). Via Team Cymru's whois service — no API key or GeoIP database needed. Takes an IP literal or AS number, not a hostname; resolve first with dns_lookup if you only have a name.
targetrequiredCurrent date, time and weekday in an IANA timezone (e.g. "Asia/Tokyo"). Call this rather than deriving the weekday from a date yourself — that is calendar arithmetic and it fails silently. Returns the date, the 24h time, the weekday in English and Japanese, the offset, UTC and the epoch, so it also serves as a clock check on this server.
timezone90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
# Debian/Ubuntusudo apt install dnsutils iputils-ping mtr-tiny whoispip install netdiag-mcp# oruv tool install netdiag-mcp/plugin marketplace add shigechika/netdiag-mcp/plugin install netdiag-mcp@netdiag-mcpclaude mcp add netdiag -- netdiag-mcpcodex mcp add netdiag -- netdiag-mcpNETDIAG_HTTP_AUTH='{"https://reports.example.ac.jp/daily/": "Bearer <token>"}'netdiag-mcp --version # print versionnetdiag-mcp --check # report missing binaries and a malformed NETDIAG_HTTP_AUTH (exit 0 when all binaries are present and the setting, if any, parses)uv run python scripts/smoke_test.pyuv run python scripts/smoke_test.py --only ping --traceback