netdiag-mcp

English | 日本語

オンデマンドのネットワーク診断のためのMCPサーバー — DNSルックアップ（DNSSEC ADビットチェック付き）、ping、mtrベースの経路レポート、TCPポートチェック、HTTPステータス/リダイレクトチェック、TLS証明書検査、WHOISを、すべて1つのサーバーから提供します。

「Xに到達できない」「DNSはまだ伝播しているか」といった報告をトリアージするために、ジャンプホストにシェルインしてその都度dig/ping/curlを実行することなく対応できるように作られています。

Tools

すべてのツールは読み取り専用で単一ターゲットです（バッチ/スイープモードなし）— これはオペレーターが手動で実行するチェックの便利なラッパーであり、スキャンツールではありません。nmapスタイルのマルチホスト/マルチポートスキャンは意図的に範囲外です。多数のホストやポートを意図的にプローブすることは、別の、より影響範囲の大きいアクションであり、専用のツールと承認フローが必要です。

tcp_port_check、http_check、tls_cert_checkは、nc/curl/opensslにシェルアウトするのではなく、Python自身のsocket/ssl/httpxスタックを使用します。そのため、これらの3つのツールは、dig/ping/mtr/whoisバイナリだけがインストールされているホスト（またはそれらがまったくないホスト）でも動作します。health_checkは、サーバー全体を失敗させることなく、欠落しているものを報告します。

dns_lookup/dnssec_checkは、transport="dot"/"doh"（digの+tls/+https）を介してDNS-over-TLSおよびDNS-over-HTTPSをサポートします。これにはBIND 9.18以降のdigが必要です。古いdigは、暗黙的にプレーンDNSにフォールバックするのではなく、フラグを完全に拒否するため、古いバイナリは、暗号化されたトランスポートでチェックしたという誤った感覚を与える代わりに、大きな音を立てて失敗します。

tls_cert_check/http_checkをベアIPアドレスに対して実行すると、SNIホスト型/CDNフロント型のオリジン（例：Cloudflareの背後）でTLSハンドシェイクが「handshake failure」などのエラーで失敗する可能性があります。TLSのSNI拡張はホスト名のみを運ぶため、IPリテラルは共有エッジ上の正しい証明書にルーティングできません。これは正常なTLS動作であり、ツールのバグではありません。ターゲットがCDNフロント型の場合は、ホスト名でチェックしてください。

Setup

1. System dependencies

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はrawソケットアクセスを必要とします。Debian/Ubuntuのmtr-tinyパッケージは、インストール時にmtr-packetヘルパーにcap_net_rawを付与するため、通常は追加設定なしで非特権サービスユーザーでも動作します。traceroute_pathがソケット権限エラーを報告する場合は、getcap "$(command -v mtr-packet)"で確認してください。その機能がない場合、traceroute_pathはサーバーをクラッシュさせる代わりに、ToolErrorでクリーンに失敗します。

2. Install

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

3. Claude Code (manual)

claude mcp add netdiag -- netdiag-mcp

環境変数は必要ありません。

CLI

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

Security notes

• すべての外部バイナリ呼び出しはargvリストを渡します（シェル文字列は決して使用しません）。そのため、ツールの引数がシェル構文に抜け出すことはありません。

• ホスト名/IPおよびポート引数は、使用前に検証され、サイズ/範囲がクランプされます。ツール入力はモデル駆動であり、他のツール呼び出しサーフェスと同様に信頼できないものとして扱われます。

• tcp_port_checkは、呼び出しごとに正確に1つのホスト:ポートに接続します。設計上、ループや範囲引数はありません。

Development

Live smoke test

単体テストはフィクスチャに対してロジックをチェックしますが、ツールが実際のデータを返さなくなったこと（死んだ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は、誰がそれが動作するかを知る方法を決定せずに追加されたツールを、ネットワークアクセスなしで検出します。

License

MIT