netdiag-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@netdiag-server YouTube isn't loading for me — can you figure out what's broken?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: sanitycheck-mcp
What it does
Part | Command | Needs an API key |
MCP server with 11 read-only network tools |
| No |
Diagnosis: every check, bottom-up, with a plain-English answer |
| No |
Agent: ask in your own words and Claude picks the tools |
| 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 wifiAdd --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 # interactiveThe 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.8finds 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 |
| Physical, data link | Up or down, addresses, MAC, speed, frame errors |
| Physical | Signal in dBm: strong, ok or weak |
| Network | IPv4 address, default gateway, DNS servers |
| Network | Replies, packet loss, latency, jitter |
| Network | Every router on the path, and where replies stop |
| Network | The routing table, including the default route |
| Data link | IP-to-MAC pairs on the local network |
| Application | Name to IP, through the system DNS or a chosen server |
| Transport | A TCP three-way handshake to a port |
| Application | HTTP status code and response time |
| 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 resolvesyoutube.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-serverClaude 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 slidesTests
pytestThe 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 toolsarp_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Free, no-API-key network lookups for AI agents — IP geolocation, DNS, WHOIS, HTTP and SSL/TLS certificate checks, and full domain health reports.
Network, domain and website diagnostics for AI clients via MCP.
Live web checks for AI agents: sitemaps, robots.txt, URL status, broken links, feeds, citations.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform real network diagnostics on the local machine, including ping, traceroute, DNS lookups, TLS checks, and more.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to check the health of internet infrastructure and specific services, helping diagnose whether issues are local or external.316 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables 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.-