Network MCP

🚀 Network MCP Server

Model Context Protocol (MCP)サーバーで、AIエージェント用のネットワーク診断ツールを提供します。重いネットワーク分析をサーバーにオフロードし、LLMが消費しやすい構造化された実行可能なデータを返すように設計されています。

✨ 主な機能

• 接続テスト：ping、traceroute、DNSルックアップ、ポートチェック、MTR
• バッチ操作：複数のホスト/ポートを同時にテスト
• ローカルネットワーク情報：インターフェース、ルート、DNS設定、ARPテーブル、接続情報を取得（クロスプラットフォーム）
• Pcap分析：scapyを使用してパケットキャプチャを分析（tsharkは不要）
• カスタムフィルタ：高度なクエリ用のscapyフィルタ式を実行（AST検証済み）
• セキュリティコントロール：ターゲット検証用の許可リスト/ブロックリストを設定可能（接続ツールで適用）
• PCAPパスガードレール：サーバーがキャプチャを読み取ることが許可されているディレクトリを制限
• スマートサマリー：人間が読めるサマリーと構造化データを返す

📦 インストール

pip install network-mcp

またはソースからインストール：

git clone https://github.com/labeveryday/network-mcp.git
cd network-mcp
pip install -e .

🚀 クイックスタート

MCPサーバーを起動します：

network-mcp

またはPythonで起動：

python -m network_mcp.server

初回実行時の推奨事項（エージェントがこのホストで安全かつ利用可能なものを判断するのに役立ちます）：

• 機能チェック：capabilitiesを呼び出して、インストールされたバイナリ（mtrなど）、アクティブなセキュリティポリシー、およびPCAPパスガードレールを確認します。
• ポリシーの決定：ターゲット検証またはPCAPアクセスを緩和/強化する必要がある場合は、起動前に環境変数を設定します。
• デフォルトで単体テストを実行：pytestは、明示的に選択しない限り統合テストをスキップします（開発については後述）。

📚 ドキュメント

診断ツール

計画ツール（純粋なCIDR/VLAN計算）

Tier 1 / Tier 2 NOCワークフロー向けに設計されています。これらのツールは純粋（ネットワーク呼び出しなし、決定論的な出力）であり、計画と検証に安全に使用できます。

入力例

• VLANマップ（両方の形式が受け付けられます）：

{
  "10": "192.168.10.0/24",
  "20": { "cidr": "192.168.20.0/24", "name": "Voice" }
}

• plan_subnetsの要件（エイリアスhostsとprefixがサポートされています）：

[
  { "vlan_id": 10, "name": "Users", "hosts": 120 },
  { "vlan_id": 20, "name": "Voice", "hosts": 60 },
  { "vlan_id": 30, "name": "Printers", "prefix": 26 }
]

外部情報ツール

接続ツール

バッチ操作ツール

ローカルネットワーク情報ツール

Linux、macOS、Windowsで動作するクロスプラットフォームツールです。

Pcap分析ツール

IDE統合

Claude Desktop

macOSの場合は~/Library/Application Support/Claude/claude_desktop_config.json、Windowsの場合は%APPDATA%\Claude\claude_desktop_config.jsonに追加します：

{
  "mcpServers": {
    "network-tools": {
      "command": ["network-mcp"]
    }
  }
}

Cursor

MCP設定に追加します：

{
  "mcpServers": {
    "network-tools": {
      "command": ["network-mcp"]
    }
  }
}

uvを使用する場合

uvでインストールした場合は、次のように設定します：

{
  "mcpServers": {
    "network-tools": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/network-mcp", "network-mcp"]
    }
  }
}

応答例

Ping

{
  "success": true,
  "target": "google.com",
  "resolved_ip": "142.250.80.46",
  "packets_sent": 4,
  "packets_received": 4,
  "packet_loss_percent": 0.0,
  "min_latency_ms": 11.2,
  "avg_latency_ms": 12.8,
  "max_latency_ms": 15.1,
  "summary": "google.com is reachable. 4/4 packets received, avg latency 12.8ms"
}

Batch Ping

{
  "success": true,
  "total_targets": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {"target": "8.8.8.8", "success": true, "avg_latency_ms": 12.5},
    {"target": "1.1.1.1", "success": true, "avg_latency_ms": 8.2},
    {"target": "google.com", "success": true, "avg_latency_ms": 15.1}
  ],
  "summary": "Batch ping: 3/3 targets reachable"
}

TCP Issues Detection

{
  "success": true,
  "file_path": "/tmp/capture.pcap",
  "total_tcp_packets": 15234,
  "issues": [
    {
      "issue_type": "retransmission",
      "count": 47,
      "severity": "medium",
      "recommendation": "Retransmissions indicate packet loss. Check for network congestion."
    }
  ],
  "has_issues": true,
  "summary": "TCP issues detected in 15234 packets: 47 retransmissions"
}

Throughput (from PCAP)

{
  "success": true,
  "file_path": "/tmp/capture.pcap",
  "total_packets_scanned": 100000,
  "conversations_analyzed": 87,
  "top_n": 3,
  "sort_by": "mbps_total",
  "conversations": [
    {
      "src_ip": "10.0.0.10",
      "src_port": 51544,
      "dst_ip": "93.184.216.34",
      "dst_port": 443,
      "protocol": "TCP",
      "packets_total": 1240,
      "bytes_total": 18423333,
      "duration_seconds": 9.84,
      "start_time": 1734567890.01,
      "end_time": 1734567899.85,
      "packets_forward": 820,
      "bytes_forward": 17600000,
      "packets_reverse": 420,
      "bytes_reverse": 823333,
      "mbps_forward": 14.308,
      "mbps_reverse": 0.669,
      "mbps_total": 14.977,
      "direction": "10.0.0.10:51544 -> 93.184.216.34:443"
    }
  ],
  "summary": "Throughput analysis: 87 conversations from 100000 packets. Top flow 10.0.0.10:51544 -> 93.184.216.34:443 at ~14.977 Mbps over 9.84s"
}

Get Interfaces

{
  "success": true,
  "interfaces": [
    {
      "name": "en0",
      "status": "up",
      "mac_address": "00:11:22:33:44:55",
      "ipv4_addresses": ["192.168.1.100"],
      "ipv6_addresses": ["fe80::1"],
      "netmask": "255.255.255.0",
      "mtu": 1500
    }
  ],
  "default_interface": "en0",
  "summary": "Found 5 interfaces (3 up). Primary: en0"
}

Get Public IP

{
  "success": true,
  "public_ip": "203.0.113.42",
  "service_used": "ipify.org",
  "summary": "Public IP: 203.0.113.42 (via ipify.org)"
}

RDAP Lookup (WHOIS-style)

{
  "success": true,
  "query": "1.1.1.1",
  "query_type": "ip",
  "rdap_url": "https://rdap.org/ip/1.1.1.1",
  "handle": "NET-1-1-1-0-1",
  "country": "AU",
  "start_address": "1.1.1.0",
  "end_address": "1.1.1.255",
  "summary": "RDAP 1.1.1.1: 1.1.1.0–1.1.1.255 (AU), handle NET-1-1-1-0-1"
}

ASN Lookup

{
  "success": true,
  "ip": "1.1.1.1",
  "asn": "13335",
  "prefix": "1.1.1.0/24",
  "country": "AU",
  "registry": "apnic",
  "allocated": "2011-08-11",
  "as_name": "CLOUDFLARENET",
  "summary": "1.1.1.1 originates from AS13335 (CLOUDFLARENET), prefix 1.1.1.0/24"
}

設定

作業ディレクトリまたは~/.network-mcp/config.yamlにconfig.yamlを作成します：

security:
  # これらのターゲットのみを許可（グロブパターン、CIDR範囲）
  allowed_targets:
    - "*.company.com"
    - "10.0.0.0/8"
    - "192.168.0.0/16"

  # これらのターゲットをブロック
  blocked_targets:
    - "*.gov"
    - "localhost"
    - "127.0.0.0/8"

  # プライベートIPをブロック
  block_private: false

  # クラウドメタデータエンドポイントをブロック（AWS、GCPなど）
  block_cloud_metadata: true

pcap:
  max_packets: 100000
  allow_custom_filters: true
  # サーバーがpcapを読み取ることが許可されているディレクトリを制限
  # （パスはチェック前に解決されます）
  allowed_paths:
    - "."
    - "~/Documents"
    - "/tmp"

環境変数：

NETWORK_MCP_ALLOWED_TARGETS="*.company.com,10.0.0.0/8"
NETWORK_MCP_BLOCKED_TARGETS="*.gov,localhost"
NETWORK_MCP_BLOCK_PRIVATE="true"
NETWORK_MCP_MAX_PACKETS="50000"
NETWORK_MCP_PCAP_ALLOWED_PATHS=".,~/Documents,/tmp"

ネットワークツールにMCPを使用する理由

• トークン効率：LLMにはコンテキスト制限があります。サーバーが重い処理（10万個のパケットを解析）を行い、生データではなく簡潔なサマリーを返します。
• より良い推論：LLMは調査する内容を決定するのに優れていますが、生の出力を解析することには向いていません。構造化データにより、より良い決定が可能になります。
• 一貫性：サーバー側の処理は決定論的です。毎回LLMがtracerouteの出力を正しく解釈することに依存する必要はありません。

サンプル

examples/ディレクトリには、Strands Agentsを使用した動作サンプルが含まれています：

クイックスタート：

cd examples
pip install strands-agents strands-agents-tools 'strands-agents[ollama]'
python ollama_agent.py

詳細なドキュメントはを参照してください。

🔧 技術詳細

開発

# クローンして開発依存関係をインストール
git clone https://github.com/labeveryday/network-mcp.git
cd network-mcp
pip install -e ".[dev]"

# 単体テストを実行（デフォルトでは統合テストはスキップされます）
pytest

# 統合テストを実行（システムツールおよび/またはネットワークアクセスが必要）
pytest -m integration

# リンティングを実行
ruff check .

プロジェクト構造

network-mcp/
├── src/network_mcp/
│   ├── __init__.py
│   ├── server.py           # FastMCPサーバー
│   ├── config.py           # 設定とセキュリティ
│   ├── tools/
│   │   ├── connectivity.py # ping、traceroute、dns、port_check、mtr、バッチ操作
│   │   ├── local.py        # ローカルネットワーク情報（インターフェース、ルートなど）
│   │   └── pcap.py         # pcap分析ツール
│   └── models/
│       └── responses.py    # Pydantic応答モデル
├── tests/
├── pyproject.toml
└── README.md

要件

• Python 3.10以上
• システムツール：ping、traceroute（ほとんどのシステムに標準搭載）
• オプション：MTRツールにはmtrが必要

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。