Network MCP

🚀 網絡MCP服務器

網絡MCP服務器是一個模型上下文協議（MCP）服務器，為AI智能體提供網絡診斷工具。它旨在將繁重的網絡分析任務卸載到服務器上，並返回經過優化的結構化、可操作的數據，以便大語言模型（LLM）使用。

✨ 主要特性

• 連接性測試：支持ping、traceroute、DNS查詢、端口檢查、MTR等功能。
• 批量操作：可同時對多個主機/端口進行測試。
• 本地網絡信息：跨平臺獲取網絡接口、路由、DNS配置、ARP表和連接信息。
• Pcap分析：使用scapy分析數據包捕獲文件，無需tshark。
• 自定義過濾器：執行scapy過濾表達式進行高級查詢，並進行AST驗證。
• 安全控制：可配置允許列表/阻止列表進行目標驗證，應用於連接性工具。
• PCAP路徑防護：限制服務器可讀取捕獲文件的目錄。
• 智能摘要：返回人類可讀的摘要以及結構化數據。

📦 安裝指南

使用pip安裝：

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計算）

專為一級/二級網絡運營中心（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安裝的情況

{
  "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"
}

批量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問題檢測

{
  "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"
}

吞吐量分析（從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"
}

獲取網絡接口信息

{
  "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"
}

獲取公共IP地址

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

RDAP查詢（WHOIS風格）

{
  "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查詢

{
  "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文件。