📡 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.

Related MCP server: perfsonar-mcp

🚀 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

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

🌐 REST endpoints (bonus)

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

⚙️ Configuration

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

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