Network-MCP: Network Diagnostic Server for AI Agents with MCP Protocol

Network MCP

A network diagnostic server based on the Model Context Protocol (MCP) that provides network analysis tools for AI agents, including connectivity testing, batch operations, obtaining local network information, packet capture analysis, etc. It supports security control and structured data output.

Monitoring Developer tools #Network diagnosis #MCP service #AI tool #Security analysis .Python

rating : 2 points

downloads : 7.8K

update time : 2025-12-29

Open Site

What is Network MCP Server?

Network MCP Server is a network diagnostic tool server specifically designed for AI assistants. It allows AI assistants (such as Claude, Cursor, etc.) to call various network tools through standard protocols to perform tasks such as network connectivity tests, network packet analysis, and obtaining local network configurations without users having to manually run complex command-line tools.

How to use Network MCP Server?

You only need to configure Network MCP Server in the supported AI assistant application, and then you can ask the AI assistant about network-related questions in natural language, such as 'Test the connection to google.com', 'Analyze this network packet file', 'View my network interface information', etc. The AI assistant will automatically call the corresponding network tools and return easy-to-understand results.

Applicable scenarios

Suitable for network administrators, developers, technical support personnel, and any users who need to quickly diagnose network problems. Especially suitable for: 1. Diagnosing network connectivity problems 2. Analyzing network performance 3. Troubleshooting network failures 4. Learning basic network knowledge 5. Automating network monitoring tasks

Main features

Connectivity testing

Provide basic network connectivity testing tools such as ping, traceroute, DNS query, port check, and MTR to help diagnose network reachability problems.

Batch operations

Support testing multiple hosts or ports simultaneously to improve diagnostic efficiency, especially suitable for monitoring multiple services or network nodes.

Local network information

Obtain local network information across platforms, including network interfaces, routing tables, DNS configurations, ARP tables, active connections, etc. Support Linux, macOS, and Windows systems.

Packet analysis

Analyze network packet capture files (PCAP) and provide advanced functions such as traffic statistics, protocol analysis, TCP problem detection, and throughput calculation.

Security control

Built-in security policies, configurable allow and block target lists to prevent misoperations or malicious use and protect network security.

Network planning tools

Provide pure calculation tools such as CIDR calculation, subnet division, and VLAN mapping verification, suitable for network planning and design work.

External intelligence

Support RDAP queries (similar to WHOIS) and ASN lookups to obtain registration information and network ownership of IP addresses and domain names.

Advantages

AI-friendly: Specifically designed for AI assistants, returning structured data instead of raw command-line output

Cross-platform: Support Linux, macOS, and Windows systems

Secure and controllable: Built-in security policies to limit access targets and file paths

Efficient processing: The server performs heavy tasks, reducing the processing burden on AI assistants

Easy to integrate: Support mainstream AI assistant applications such as Claude Desktop and Cursor

Limitations

Requires system tools: Depends on system commands such as ping and traceroute, and some functions require administrator privileges

Network-dependent: Some functions require a network connection to work properly

Complex configuration: Advanced security policies need to be manually configured

Learning curve: Non-technical users may need time to understand network concepts

How to use

Install Network MCP Server

Install the Network MCP Server software package via pip

Configure the AI assistant

Add the Network MCP Server configuration to the AI assistant application you are using

Start the server

Run Network MCP Server, and it will automatically establish a connection with the AI assistant

Start using

Ask the AI assistant about network-related questions in natural language, and the AI assistant will automatically call the corresponding network tools

Usage examples

Diagnose website inaccessibility

When a user reports that a certain website is inaccessible, the AI assistant can automatically perform a series of network tests to locate the problem.

Analyze network performance problems

The user feels that the network speed has slowed down and needs to analyze the network traffic and performance.

Check local network configuration

The user needs to understand their network settings to optimize the network for remote work or gaming.

Plan subnet division

Network administrators need to plan IP address allocation for a new office.

Frequently Asked Questions

Is Network MCP Server secure? Will it be misused?

Which system tools do I need to install?

Which AI assistant applications are supported?

How large a PCAP file can be analyzed?

How to customize the security policy?

Does the Windows system support all functions?

Related resources

GitHub repository

Source code, issue tracking, and the latest version

PyPI page

Python package installation page

Example code

Usage examples and demonstration applications

Model Context Protocol documentation

Official documentation of the MCP protocol

Basic knowledge of network diagnosis

Introduction to network monitoring and diagnostic concepts

🚀 Network MCP Server

A Model Context Protocol (MCP) server that offers network diagnostic tools for AI agents. It's designed to offload complex network analysis tasks to the server and return structured, actionable data optimized for consumption by Large Language Models (LLMs).

✨ Features

Connectivity Testing: Perform ping, traceroute, DNS lookups, port checks, and MTR.
Batch Operations: Test multiple hosts/ports simultaneously.
Local Network Info: Retrieve interfaces, routes, DNS configuration, ARP table, and connections across different platforms.
Pcap Analysis: Analyze packet captures using scapy without the need for tshark.
Custom Filters: Execute scapy filter expressions for advanced queries with AST validation.
Security Controls: Configure allowlists/blocklists for target validation in connectivity tools.
PCAP Path Guardrails: Restrict the directories from which the server can read packet captures.
Smart Summaries: Return human-readable summaries along with structured data.

📦 Installation

You can install the network-mcp package using pip:

pip install network-mcp

Or, you can install it from the source:

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

🚀 Quick Start

To run the MCP server, you can use the following command:

network-mcp

Alternatively, you can run it with Python:

python -m network_mcp.server

For the first run, here are some recommendations to help agents determine what's safe and available on the host:

Check capabilities: Call capabilities to view installed binaries (such as mtr), the active security policy, and PCAP path guardrails.
Decide on policy: If you need to adjust target validation or PCAP access, set the environment variables before starting the server.
Run unit tests by default: pytest skips integration tests unless you explicitly opt in (see Development section).

💻 Usage Examples

Available Tools

Diagnostics

Tool	Description
`capabilities`	Report runtime capabilities, including installed binaries like `mtr`, the active security policy, and pcap path guardrails, to help agents plan tool usage.

Planning (Pure CIDR/VLAN math)

These tools are designed for Tier 1 / Tier 2 NOC workflows. They are pure (no network calls, deterministic outputs) and safe for planning and validation.

Tool	Description
`cidr_info`	Provide CIDR primitives (IPv4/IPv6), such as network, usable range, mask/wildcard, and counts.
`ip_in_subnet`	Check if an IP is within a subnet and if it's a usable host address.
`subnet_split`	Split a CIDR into equal-size child subnets (by new prefix or power-of-two count).
`cidr_summarize`	Collapse/aggregate CIDRs into summarized routes (IPv4/IPv6 handled separately).
`check_overlaps`	Find overlaps and containment conflicts between CIDRs.
`validate_vlan_map`	Validate a 1-subnet-per-VLAN map and identify overlaps.
`find_vlan_for_ip`	Determine which VLAN matches an IP from a provided VLAN map.
`ip_in_vlan`	Check if an IP belongs to a VLAN; if not, provide a best-guess VLAN match (when unique).
`plan_subnets`	Allocate VLAN subnets from a parent IPv4 block in a deterministic manner.

Input examples

VLAN map (both formats are accepted):

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

plan_subnets requirements (aliases hosts and prefix are supported):

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

External Intel

Tool	Description
`rdap_lookup`	Perform a WHOIS-style lookup using RDAP for domains and IPs.
`asn_lookup`	Look up the origin ASN for an IP (BGP origin intelligence).

Connectivity Tools

Tool	Description
`ping`	Conduct an ICMP ping with latency statistics and packet loss information.
`traceroute`	Analyze the path, showing each hop with latency.
`dns_lookup`	Perform DNS resolution (A, AAAA, MX, TXT, etc.) and reverse lookups.
`port_check`	Test TCP port connectivity and grab banners.
`mtr`	Combine traceroute and ping with per-hop statistics.

Batch Operations

Tool	Description
`batch_ping`	Ping multiple hosts concurrently.
`batch_port_check`	Check multiple ports on a single host.
`batch_dns_lookup`	Resolve multiple hostnames in parallel.

Local Network Info Tools

These cross-platform tools work on Linux, macOS, and Windows.

Tool	Description
`get_interfaces`	List network interfaces with IPs, MACs, and status.
`get_routes`	Retrieve the routing table with the default gateway.
`get_dns_config`	Get the configured DNS servers and search domains.
`get_arp_table`	Obtain the ARP cache (IP to MAC mappings).
`get_connections`	List active TCP/UDP connections.
`get_public_ip`	Get the public/external IP address as seen from the internet.

Pcap Analysis Tools

Tool	Description
`pcap_summary`	Provide high-level capture stats, including packets, duration, protocols, and top talkers.
`get_conversations`	Identify network flows/conversations between endpoints.
`analyze_throughput`	Analyze the observed throughput (Mbps) per conversation/flow, including the dominant direction and duration.
`find_tcp_issues`	Detect retransmissions, resets, zero windows, and duplicate ACKs.
`analyze_dns_traffic`	Analyze DNS queries, failures, and slow responses.
`filter_packets`	Extract packets by IP, port, or protocol.
`get_protocol_hierarchy`	Break down protocols by packets and bytes.
`custom_scapy_filter`	Execute custom scapy filter expressions.

IDE Integration

Claude Desktop

Add the following configuration to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Add the following to your MCP settings:

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

Using with uv

If you installed with uv, use the following configuration:

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

Example Responses

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

📚 Documentation

Configuration

You can create a config.yaml file in your working directory or in ~/.network-mcp/config.yaml:

security:
  # Only allow these targets (glob patterns, CIDR ranges)
  allowed_targets:
    - "*.company.com"
    - "10.0.0.0/8"
    - "192.168.0.0/16"

  # Block these targets
  blocked_targets:
    - "*.gov"
    - "localhost"
    - "127.0.0.0/8"

  # Block private IPs
  block_private: false

  # Block cloud metadata endpoints (AWS, GCP, etc.)
  block_cloud_metadata: true

pcap:
  max_packets: 100000
  allow_custom_filters: true
  # Restrict which directories the server is allowed to read pcaps from.
  # (Paths are resolved before checking.)
  allowed_paths:
    - "."
    - "~/Documents"
    - "/tmp"

You can also use environment variables:

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"

Why MCP for Network Tools?

Token Efficiency: LLMs have context limits. The server performs heavy processing (such as parsing 100k packets) and returns concise summaries instead of raw data.
Better Reasoning: LLMs are better at deciding what to investigate rather than parsing raw output. Structured data enables better decision-making.
Consistency: Server-side processing is deterministic, so you don't have to rely on the LLM to correctly interpret traceroute output every time.

Examples

The examples/ directory contains working examples using Strands Agents:

Example	Description
`ollama_agent.py`	An interactive chat agent using Ollama (local models).
`incident-demo/`	A self-contained demo where an AI diagnoses network outages with voice alerts.
`eval_agent.py`	Evaluate how well models use the network tools.

To quickly start with the examples, follow these steps:

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

For detailed documentation, refer to .

🔧 Technical Details

Development

# Clone and install dev dependencies
git clone https://github.com/labeveryday/network-mcp.git
cd network-mcp
pip install -e ".[dev]"

# Run unit tests (integration tests are skipped by default)
pytest

# Run integration tests (requires system tools and/or network access)
pytest -m integration

# Run linting
ruff check .

Project Structure

network-mcp/
├── src/network_mcp/
│   ├── __init__.py
│   ├── server.py           # FastMCP server
│   ├── config.py           # Configuration and security
│   ├── tools/
│   │   ├── connectivity.py # ping, traceroute, dns, port_check, mtr, batch ops
│   │   ├── local.py        # local network info (interfaces, routes, etc.)
│   │   └── pcap.py         # pcap analysis tools
│   └── models/
│       └── responses.py    # Pydantic response models
├── tests/
├── pyproject.toml
└── README.md