shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

network-mcp

一个基于模型上下文协议（MCP）的网络诊断服务器，为AI代理提供网络分析工具，包括连通性测试、批量操作、本地网络信息获取、数据包捕获分析等功能，支持安全控制和结构化数据输出。

article

README

🚀 网络MCP服务器

网络MCP服务器是一个模型上下文协议（MCP）服务器，为AI智能体提供网络诊断工具。它旨在将繁重的网络分析任务卸载到服务器上，并返回经过优化的结构化、可操作的数据，以便大语言模型（LLM）使用。

PyPI version Python 3.10+ License: MIT

✨ 主要特性

  • 连接性测试：支持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默认跳过集成测试，除非手动选择运行（详见开发部分）。

💻 使用示例

可用工具

诊断工具

| 工具 | 描述 | |------|-------------| | capabilities | 报告运行时功能（如已安装的二进制文件mtr、当前安全策略、pcap路径防护设置），以便智能体规划工具使用。 |

规划工具（纯CIDR/VLAN计算）

专为一级/二级网络运营中心（NOC）工作流程设计。这些工具是纯计算工具（无网络调用，输出确定），可安全用于规划和验证。 | 工具 | 描述 | |------|-------------| | cidr_info | CIDR基本信息（IPv4/IPv6）：网络、可用范围、掩码/通配符、数量。 | | ip_in_subnet | 检查IP是否在子网内以及是否为可用的主机地址。 | | subnet_split | 将CIDR划分为大小相等的子子网（通过新前缀或2的幂次方数量）。 | | cidr_summarize | 将CIDR合并/聚合为汇总路由（IPv4/IPv6分别处理）。 | | check_overlaps | 查找CIDR之间的重叠/包含冲突。 | | validate_vlan_map | 验证每个VLAN一个子网的映射并显示重叠情况。 | | find_vlan_for_ip | 从提供的VLAN映射中查找与IP匹配的VLAN（一级“此IP属于哪个VLAN？”）。 | | ip_in_vlan | 检查IP是否属于某个VLAN；如果不属于，提供最佳匹配的VLAN（唯一匹配时）。 | | plan_subnets | 从父IPv4块分配VLAN子网（确定性分配）。 |

输入示例

  • 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 }
]

外部情报工具

| 工具 | 描述 | |------|-------------| | rdap_lookup | 使用RDAP进行WHOIS风格的域名和IP查询。 | | asn_lookup | 查询IP的起源自治系统号（ASN）（BGP起源情报）。 |

连接性工具

| 工具 | 描述 | |------|-------------| | ping | ICMP ping，提供延迟统计和丢包率。 | | traceroute | 路径分析，显示每一跳的延迟。 | | dns_lookup | DNS解析（A、AAAA、MX、TXT等）和反向查询。 | | port_check | TCP端口连接测试，支持抓取横幅信息。 | | mtr | 结合traceroute和ping，提供每一跳的统计信息。 |

批量操作工具

| 工具 | 描述 | |------|-------------| | batch_ping | 同时对多个主机进行ping测试。 | | batch_port_check | 检查单个主机上的多个端口。 | | batch_dns_lookup | 并行解析多个主机名。 |

本地网络信息工具

跨平台工具，支持Linux、macOS和Windows。 | 工具 | 描述 | |------|-------------| | get_interfaces | 列出网络接口，包括IP、MAC和状态信息。 | | get_routes | 获取路由表，包括默认网关。 | | get_dns_config | 获取配置的DNS服务器和搜索域。 | | get_arp_table | 获取ARP缓存（IP到MAC的映射）。 | | get_connections | 列出活动的TCP/UDP连接。 | | get_public_ip | 获取从互联网可见的公共/外部IP地址。 |

Pcap分析工具

| 工具 | 描述 | |------|-------------| | pcap_summary | 高级捕获统计信息：数据包数量、持续时间、协议、主要通信方。 | | get_conversations | 网络端点之间的流量/会话信息。 | | analyze_throughput | 观察每个会话/流量的吞吐量（Mbps），包括主要方向和持续时间。 | | find_tcp_issues | 检测TCP重传、重置、零窗口、重复ACK等问题。 | | analyze_dns_traffic | 分析DNS查询、失败和慢响应情况。 | | filter_packets | 按IP、端口或协议提取数据包。 | | get_protocol_hierarchy | 按数据包和字节数统计协议分布。 | | custom_scapy_filter | 执行自定义的scapy过滤表达式。 |

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的实际示例： | 示例 | 描述 | |---------|-------------| | ollama_agent.py | 使用Ollama（本地模型）的交互式聊天智能体。 | | incident-demo/ | 独立演示：AI诊断网络故障并提供语音警报。 | | eval_agent.py | 评估模型使用网络工具的效果。 |

快速开始：

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

完整文档请参阅examples/README.md。

开发

# 克隆仓库并安装开发依赖
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文件。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client