Skip to main content
Glama
netdiag-server
by ZANYANBU

Network MCP Server with a Diagnosis Agent

Tells you which network layer is broken, and how to fix it.

tests Python 3.10+ MCP Windows · macOS · Linux MIT

21CSC302J Computer Networks · SRM Institute of Science and Technology

When the Internet stops working you only see the symptom: "YouTube won't load." The cause can sit at any layer: a weak Wi-Fi signal, a missing IP address, a wrong gateway, a broken route at the ISP, or a DNS server that has stopped answering.

This project gives an AI agent the same tests a network engineer would run, through the Model Context Protocol (MCP), plus a diagnosis method that works from the bottom layer up and stops at the first failure.

Contents

Related MCP server: sanitycheck-mcp

What it does

Part

Command

Needs an API key

MCP server with 11 read-only network tools

netdiag-server

No

Diagnosis: every check, bottom-up, with a plain-English answer

netdiag diagnose youtube.com

No

Agent: ask in your own words and Claude picks the tools

netdiag-agent "YouTube is not loading"

Yes

A real run on a home network:

And the same command when the DNS server stops answering (simulated, as in the tests):

Quick start

Python 3.10 or newer.

git clone https://github.com/ZANYANBU/network-mcp-diagnosis-agent.git
cd network-mcp-diagnosis-agent
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[test]"
netdiag diagnose youtube.com       # full check, no AI needed
netdiag ping 8.8.8.8
netdiag traceroute 8.8.8.8
netdiag dns youtube.com --server 1.1.1.1
netdiag ipconfig
netdiag wifi

Add --json to diagnose for machine-readable output.

The agent

export ANTHROPIC_API_KEY=...       # from console.anthropic.com
netdiag-agent "YouTube is not loading"
netdiag-agent                      # interactive

The agent starts the MCP server itself, hands Claude its tools, and prints each tool call as it happens.

How the diagnosis works

Each layer depends on the ones below it, so the first failure is the answer. Two checks do extra work to give a precise diagnosis:

  • Internet unreachable: a traceroute to 8.8.8.8 finds the last hop that replied, which separates "your router's uplink" from "inside the ISP".

  • DNS fails: the same lookup is retried through 1.1.1.1. If that works, your DNS server is at fault; if not, the name itself is wrong.

Even when everything passes, it warns about packet loss, high latency, jitter and a weak Wi-Fi signal.

The tools

Tool

Layer

What it tells you

interfaces

Physical, data link

Up or down, addresses, MAC, speed, frame errors

wifi_signal

Physical

Signal in dBm: strong, ok or weak

ip_config

Network

IPv4 address, default gateway, DNS servers

ping

Network

Replies, packet loss, latency, jitter

traceroute

Network

Every router on the path, and where replies stop

route_table

Network

The routing table, including the default route

arp_table

Data link

IP-to-MAC pairs on the local network

dns_lookup

Application

Name to IP, through the system DNS or a chosen server

port_check

Transport

A TCP three-way handshake to a port

http_check

Application

HTTP status code and response time

diagnose

All

The whole bottom-up sequence in one call

Safe by design. Every tool only reads; none changes a setting. Host names are validated, and commands run as argument lists without a shell, so a request like 8.8.8.8; rm -rf / is refused.

Live demo in Cisco Packet Tracer

The packet-tracer/ folder holds a ready-made network, Network-Diagnosis-Demo.pkt, built and tested in Packet Tracer 9.0.1.

  • Home LAN 192.168.1.0/24: the PCs get their addresses from HomeRouter's DHCP server.

  • Link between routers 10.0.0.0/30, with OSPF area 0 on both routers.

  • ISP side 203.0.113.0/24: a DNS server that resolves youtube.com, and the web server it points to.

The same checks the agent runs, typed on PC0 in the saved network:

The demo breaks one layer at a time (a shut switch port, a wrong gateway, a removed OSPF network, the DNS service turned off) and diagnoses each live. Step-by-step instructions, the router configurations and what to say are in Packet-Tracer-Live-Demo.pdf.

Use it from Claude

Claude Code

claude mcp add network-diagnosis -- /full/path/to/.venv/bin/netdiag-server

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "network-diagnosis": { "command": "/full/path/to/.venv/bin/netdiag-server" }
  }
}

Any other MCP client works the same way: it starts netdiag-server and talks to it over standard input and output.

Project layout

netdiag/
  tools.py        the read-only network checks, one function each
  parse.py        turns ping, traceroute, route and ARP output into data (Windows, macOS, Linux)
  diagnose.py     the bottom-up diagnosis and its plain-English report
  server.py       the MCP server
  agent.py        the Claude agent that uses the server
  cli.py          the netdiag command
tests/            parsers and every fault scenario
packet-tracer/    the demo network, router configs and the demo guide
docs/             diagrams, screenshots and the presentation slides

Tests

pytest

The tests feed saved command outputs from all three operating systems into the parsers, and run the diagnosis on a made-up network broken one layer at a time: link down, DHCP failure, wrong gateway, a routing break inside the ISP, a dead DNS server, a misspelt name and a closed port. They run on Windows, macOS and Linux on every push.

Syllabus mapping

Unit

Where it shows up

1 · Introduction to networks

Interfaces, transmission media, Wi-Fi signal, latency, jitter, packet loss

2 · Addressing

IPv4, subnet masks, DHCP and 169.254 addresses, default gateway

3 · Routing

Routing table, default route, traceroute and TTL, OSPF in the demo

4 · Medium access control

MAC addresses, ARP, frame error counters

5 · Transport and application

TCP handshake, ports, DNS, HTTP

The presentation slides walk through each unit with diagrams.

Released under the MIT License.

Available Tools

11 tools
arp_tableC

IP-to-MAC address pairs this computer has learned on the local network.

Inputs: no named parameters. Returns: result

diagnoseB

Run the full bottom-up diagnosis against a site and say which layer fails and how to fix it.

Args: target: Host name or IP address the user is trying to reach, e.g. youtube.com. port: TCP port of the service, 443 for websites.

Inputs: port, target. Returns: result

dns_lookupA

Resolve a name to IP addresses with the system's DNS, or with a given DNS server such as 1.1.1.1.

Args: name: Host name to look up, e.g. youtube.com. server: Optional DNS server IP to ask instead of the system's own.

Inputs: name (required), server.

http_checkA

Request a web page's headers and report the HTTP status code and response time.

Args: url: Address such as https://youtube.com; https is assumed if no scheme is given.

Inputs: url (required).

interfacesA

List network interfaces: up or down, IPv4/IPv6 addresses, MAC, speed and error counters (physical and data link layers).

Inputs: no named parameters. Returns: result

ip_configA

This computer's IPv4 addresses, default gateway and DNS servers, like ipconfig.

Inputs: no named parameters.

pingA

Ping a host: replies, packet loss, average latency and jitter.

Args: host: Host name or IP address. count: Number of echo requests, 1 to 10.

Inputs: host (required), count.

port_checkA

Try a TCP three-way handshake to host:port and report open, refused or timed out.

Args: host: Host name or IP address. port: TCP port, e.g. 443 for HTTPS, 80 for HTTP, 53 for DNS.

Inputs: host (required), port.

route_tableC

The computer's routing table, including the default route (0.0.0.0/0).

Inputs: no named parameters. Returns: result

tracerouteB

List every router on the path to a host and where the replies stop.

Args: host: Host name or IP address. max_hops: Most routers to try, 1 to 30.

Inputs: host (required), max_hops.

wifi_signalA

Wi-Fi signal strength in dBm and a strong/ok/weak rating, if the computer is on Wi-Fi.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 11 tools

    Disambiguation4/5

    Each tool maps to a distinct diagnostic layer or probe (interface listing, Wi-Fi, IP config, routing, ARP, DNS, ping, traceroute, port, HTTP), so boundaries are mostly crisp. The only mild overlap is the aggregate `diagnose` versus the individual probes it presumably invokes, but its 'identify failing layer and fix' framing distinguishes it.

    Naming Consistency4/5

    Most names follow a noun_noun or noun-phrase convention (wifi_signal, ip_config, dns_lookup, port_check, http_check, route_table, arp_table) with `interfaces` as a plain noun. `diagnose`, `ping`, and `traceroute` are verb/vague outliers, but they are conventional names for these utilities and remain readable.

    Tool Count5/5

    Eleven tools is well within the ideal 3-15 range and each covers a distinct layer or probe in a bottom-up network diagnosis workflow. Nothing feels redundant or missing at the count level.

    Completeness4/5

    The surface covers physical/data-link (interfaces, wifi_signal), network (ip_config, route_table, arp_table), transport (ping, traceroute, port_check), and application (dns_lookup, http_check) layers, plus an aggregate `diagnose`. Minor gaps exist—no active connection listing (netstat-equivalent), DHCP/lease info, or bandwidth/MTU test—but core diagnostic workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to check the health of internet infrastructure and specific services, helping diagnose whether issues are local or external.
      3
      16 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to debug local networks in plain language by pinging, sweeping subnets, tracing routes, resolving DNS, scanning ports, inspecting ARP tables and active connections, and checking URL reachability.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to safely troubleshoot networks through read-only tools for device inventory, interface status, VLAN paths, BGP neighbors, route lookups, and interface error detection. Integrates with Microsoft Copilot Studio and Teams for natural-language-driven network diagnostics.
      -