📡 Network Monitor — MCP Server + Real-time Web Dashboard

A single Node.js project that does two things:

1. An MCP server exposing network tools (get_network_status, ping_device, scan_network) that any MCP client (Claude Desktop, etc.) can call.
2. A modern web dashboard on port 39824 with live latency graphs, a device list, and a scan button — dark-mode, clean, and mobile-friendly so you can watch it from your phone.

It is built entirely on Node's child_process calling the system ping and arp commands — no native modules, no root required — so it runs the same on macOS, Linux, and Windows.

---

✨ Features

• Real-time latency to your gateway (192.168.18.1) and the internet (8.8.8.8), sampled every 2 s and streamed to the browser over WebSockets.
• Live latency chart (Chart.js) with a smooth rolling 40-point window and separate gateway/internet series.
• Active device list for the 192.168.18.0/24 subnet — each device shows its IP, ping time, MAC address, and vendor (offline OUI lookup).
• One-click network scan — ping-sweeps all 254 hosts in bounded-concurrency batches, then enriches responders from the ARP cache. Live progress bar included.
• Beautiful UI — dark mode, glassy cards, status badges (excellent / good / slow / offline), gateway highlighting, responsive table on desktop and stacked cards on mobile.
• MCP tools callable from any MCP-compatible client.
• Zero native dependencies — only express, ws, and the MCP SDK.

---

🚀 Quick start

npm install      # already done if you're reading this after setup
npm start        # starts the web dashboard on port 39824

Then open http://localhost:39824 — or from your phone, http://<your-computer-ip>:39824 (same Wi-Fi).

The server is typically already running after setup. Check with:

curl -s http://localhost:39824/api/status

---

🖥️ Running modes

Command	What it runs
npm start / node index.js	Web dashboard only (port 39824).
npm run mcp / node mcp-server.js	MCP server over stdio — and it also boots the dashboard, so you get tools + UI from one command.

To run the MCP server without the web dashboard (e.g. inside an MCP client that only wants stdio):

NM_NO_DASHBOARD=1 node mcp-server.js

---

🔌 Using it as an MCP server

Add this to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "network-monitor": {
      "command": "node",
      "args": ["/absolute/path/to/network-mcp/mcp-server.js"],
      "env": { "NM_NO_DASHBOARD": "1" }
    }
  }
}

Exposed tools

Tool	Description	Arguments
get_network_status	Latency + reachability to the gateway and internet host, plus online/offline.	(none)
ping_device	Ping one IP/hostname once; returns alive + rtt (ms).	host (required), timeoutMs (optional)
scan_network	Ping-sweep the /24 subnet and return active devices with MAC + vendor.	subnet (optional, e.g. "192.168.18")

---

🌐 REST endpoints (bonus)

The dashboard is driven by WebSockets, but these are handy for scripting/debugging:

Endpoint	Returns
GET /api/status	Current gateway/internet latency snapshot.
GET /api/scan	Runs a full subnet scan and returns the device list.
GET /api/config	Active gateway/internet/subnet configuration.

---

⚙️ Configuration

All settings have sensible defaults and can be overridden with environment variables:

Variable	Default	Meaning
NM_PORT	39824	Web dashboard port.
NM_GATEWAY	192.168.18.1	Gateway host to monitor.
NM_INTERNET	8.8.8.8	Internet host to monitor.
NM_SUBNET	192.168.18	First three octets of the /24 to scan.
NM_SAMPLE_MS	2000	Latency sampling interval (ms).
NM_PING_TIMEOUT	1000	Per-ping timeout (ms).
NM_NO_DASHBOARD	(unset)	Set to 1 to run MCP without the web server.

Example — monitor a different network:

NM_GATEWAY=10.0.0.1 NM_INTERNET=1.1.1.1 NM_SUBNET=10.0.0 npm start

---

📱 Watching from your phone

1. Find your computer's LAN IP (macOS: ipconfig getifaddr en0, Linux: hostname -I).
2. On your phone (same Wi-Fi), open http://<that-ip>:39824.
3. The UI is fully responsive — latency cards, live chart, and a stacked device list.

---

🧩 How it works

lib/network.js    ← ping / arp via child_process, RTT parsing, subnet sweep, vendor lookup
lib/oui.js        ← compact offline MAC-prefix → vendor table
lib/dashboard.js  ← Express static server + WebSocket live feed + latency sampling loop
public/index.html ← single-page dashboard (Tailwind CDN + Chart.js + WebSocket client)
mcp-server.js     ← MCP stdio server exposing the three tools (also boots the dashboard)
index.js          ← dashboard-only entry point

• Ping flags are chosen per-platform (-t on macOS, -W on Linux, -w on Windows) and RTT is parsed from time=… ms across all of them.
• Scanning pings hosts .1–.254 in batches of 32, then reads arp -a to attach MAC + vendor to responders (the sweep is what populates the ARP cache).
• Vendor lookup is a curated offline OUI table (Apple, Google, TP-Link, Ubiquiti, Espressif/ESP, Raspberry Pi, Samsung, etc.). Unlisted prefixes show Unknown — no external calls are ever made.

---

🛠️ Troubleshooting

• No devices found on scan: confirm your machine really is on 192.168.18.x (ipconfig getifaddr en0 / ip addr). If not, set NM_SUBNET / NM_GATEWAY to match.
• Vendor shows "Unknown": the OUI table is intentionally compact; the MAC is still shown. It's cosmetic and offline by design.
• Port already in use: something else holds 39824 — set NM_PORT to another port.
• Dashboard blank / not updating: it needs internet for the Tailwind & Chart.js CDNs; check the connection pill in the header (green = live WebSocket).

---

📄 License

MIT