netdiag MCP

netdiag-mcp

English | 日本語

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

「X に接続できない」「DNS はもう伝播したか」といった報告をトリアージするために作られており、個別の dig／ping／curl を実行するたびにジャンプホストへシェル接続する必要はありません。

ツール

ツール	目的
dns_lookup	dig を使って DNS レコード（A/AAAA/MX/TXT/NS/CNAME/SOA/PTR/CAA）を解決します。任意で特定のリゾルバーを指定し、通常の DNS／DoT／DoH を使えます
dnssec_check	検証済みの既知のリゾルバーに問い合わせ、AD ビットが設定されているかを報告します（通常の DNS／DoT／DoH）。通常の dig の応答に RRSIG が含まれているだけでは、検証されたことの証明にはならないため、DNSSEC 検証を確認できる唯一の信頼できる方法です
ping_host	ICMP ping（回数は 1～10 に制限されます）
traceroute_path	mtr --report によるホップごとの経路／損失レポート（固定回数で実行され、ライブ／連続実行ではありません）
tcp_port_check	TCP ポートが開いているかを確認します。通常のソケット接続であり、ポートスキャンではありません
http_check	URL に HEAD／GET リクエストを送り、ステータス、リダイレクトチェーン、レイテンシを報告します
http_get	URL に GET リクエストを送り、本文を返します。テキスト形式のみ（text/*、JSON、XML、JavaScript、YAML、+json／+xml）に対応し、上限は 1 MiB です。リダイレクト先も含め、ループバック、リンクローカル、クラウドメタデータの宛先は拒否します
tls_cert_check	ホストが提示する証明書を取得し、サブジェクト／発行者／有効期間／SAN を報告します
whois_lookup	ドメインの WHOIS ルックアップ
asn_lookup	Team Cymru の WHOIS サービスを使って、IP アドレスの ASN と国コード、または AS 番号の組織情報を取得します。API キーも GeoIP データベースも不要です
current_time	IANA タイムゾーンで現在の日付、時刻、曜日を返します。日付から曜日を算出する処理は、算術計算が気づかれないまま失敗することがあるため、曜日はデータとして返されます。UTC とエポックも報告するため、時計の確認にも使えます
health_check	バージョンと、ラップ対象のバイナリ（dig／ping／mtr／whois）のうち PATH 上にあるものを報告します

すべてのツールは読み取り専用で、単一の対象を扱います（バッチ／一括スキャンモードはありません）。オペレーターが手作業で行うチェックを便利に実行するためのラッパーであり、スキャンツールではありません。nmap のような複数ホスト／複数ポートのスキャンは意図的に対象外です。多数のホストやポートを意図的に調査するのは、影響範囲がより大きい別のアクションであり、専用のツールと承認フローが必要です。

tcp_port_check、http_check、http_get、tls_cert_check は、nc／curl／openssl をシェルから実行するのではなく、Python 独自のソケット／ssl／httpx スタックを使います。そのため、この 4 つのツールは dig／ping／mtr／whois のバイナリだけがインストールされたホストでも（あるいはそれらが 1 つもなくても）動作します。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 の背後）では、「handshake failure」などのエラーで 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 には raw socket へのアクセスが必要です。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 Code からサーバーをインストールできます。

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

プラグインは uvx netdiag-mcp を起動します。環境変数は必要ありません。前提条件は上記のシステム依存関係のみで、それらがなくても TCP、HTTP、TLS のチェックは動作します。

Claude Code を実行するプロセスの PATH に uvx が含まれている必要があります。通常、ログインシェルには含まれていますが、GUI から起動したアプリには含まれていない場合があります。プラグインが起動しない場合は、uv をシステム全体にインストールしてください。

4. Claude Code（手動）

claude mcp add netdiag -- netdiag-mcp

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

5. Codex

codex mcp add netdiag -- netdiag-mcp

stdio サーバーを起動するその他の MCP クライアントも同様に動作します。コマンドとして netdiag-mcp を指定してください。

オプション：http_get の認証情報

http_get は、設定済みの https プレフィックス配下の URL に対して Authorization ヘッダーを送信できます。これにより、認証情報をモデルに渡さずに、保護された JSON エンドポイントを読み取れます。NETDIAG_HTTP_AUTH に、プレフィックスとヘッダー値を対応付けた JSON オブジェクトを設定してください。

NETDIAG_HTTP_AUTH='{"https://reports.example.ac.jp/daily/": "Bearer <token>"}'

• ヘッダーは、解析済み URL を比較してリクエストごと、リダイレクトの各ホップごとに選択されます（https のみ、ホストとポートが完全一致し、パスは / の境界でプレフィックスに一致する必要があります）。それ以外の場所へのリダイレクトでは、ヘッダーと、ヘッダーを付けている間に設定された Cookie が削除されます。 user@host の URL は一致しません。また、英字、数字、.、_、~、-、/ 以外を含むパス（%、;、.／.. セグメントを含むパス）も一致しないため、サーバーが一致した URL を正規化してプレフィックスの範囲外にすることはできません。一致するプレフィックスが複数ある場合は、最も長いものが優先されます。大文字小文字、:443、末尾のドットだけが異なるプレフィックスは、重複として拒否されます。値には印字可能な ASCII 文字のみ使用できます。
• netdiag-mcp は値を自身の出力、エラー、health_check に含めません。最終ホップで認証情報が送信された場合、結果のステータス行には auth=applied と表示され、health_check には設定済みプレフィックスが正規化された形式で（値は表示せずに）記載されます。不正なプレフィックスは、文字列ではなく位置で示されます。プレフィックス配下のレスポンス本文では値とそのトークン部分が [redacted] に置き換えられますが、エンドポイントがその値を変換すると（たとえば base64 化する場合）、それでも漏えいする可能性があります。そのため、プレフィックスは管理下のエンドポイントにのみ設定してください。
• 値の形式が不正な場合は、エラーが明示的に返されます。http_get はエラーを返し、health_check は degraded を報告します。
• 認証情報は環境変数からのみ読み込まれます。同じユーザーで複数のインスタンスを実行する場合（たとえば、多くのユーザーに公開するインスタンスと、利用者を制限したインスタンスを実行する場合）、認証情報を送信させるインスタンスの環境にのみ設定してください。ファイルを使うと、すべてのインスタンスで共有されます。

CLI

netdiag-mcp --version   # print version
netdiag-mcp --check     # report missing binaries and a malformed NETDIAG_HTTP_AUTH (exit 0 when all binaries are present and the setting, if any, parses)

セキュリティに関する注意事項

• すべての外部バイナリの呼び出しには argv リストを渡します（シェル文字列は使用しません）。そのため、ツールの引数からシェル構文を実行することはできません。
• ホスト名／IP とポートの引数は、使用前に検証され、サイズと範囲が制限されます。ツールへの入力はモデルが決定するため、他のツール呼び出しと同様に信頼できないものとして扱われます。
• tcp_port_check は呼び出しごとに、ホストとポートの組み合わせを 1 つだけ接続します。設計上、ループや範囲を指定する引数はありません。
• オプションの http_get 認証情報が設定済みの https プレフィックスの外へ送信されることはなく、netdiag-mcp がそれを出力することもありません。レスポンス本文に認証情報が含まれる場合はサーバー側の動作によるものです（上記を参照）。

開発

ライブスモークテスト

ユニットテストではフィクスチャに対するロジックを検証しますが、ツールが実データを返さなくなったことまでは分かりません（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