Network MCP Server with a Diagnosis Agent

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

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

• What it does

• Quick start

• How the diagnosis works

• The tools

• Live demo in Cisco Packet Tracer

• Use it from Claude

• Project layout

• Syllabus mapping

• Team

Related MCP server: connectivity-diagnostics

What it does

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

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

The presentation slides walk through each unit with diagrams.

Released under the MIT License.