Netexpert MCP

netexpert-mcp

*"What's on my network, is my link healthy, is this machine safe, and why is X slow?"*

— answered by an AI, on your LAN, in one conversation.

netexpert is a cross-platform local-network diagnostics & security-posture MCP server for AI clients (Claude Desktop, Claude Code, or any client that speaks MCP). Windows, Linux, macOS — one normalized JSON envelope, 31 tools, zero config on first run, read-only by default.

It's the *local host + LAN* half of a home-lab toolkit — the NAS half already exists as ugnas-mcp, and the two compose.

Also listed in the MCP registry as io.github.Omodaka9375/netexpert-mcp.

Install

The package is on npm — no clone, no build:

# run once, on demand (no install)

npx -y netexpert-mcp

or install globally

npm install -g netexpert-mcp netexpert-mcp

Wire it into your MCP client (stdio):

{

"mcpServers": { "netexpert": { "command": "npx", "args": ["-y", "netexpert-mcp"] } } }

That's it — first run needs no config file, no environment variables, nothing. Ask your client *"what devices are on my network?"* and it has the tools to answer.

Optional HTTP transport (stateless, same JSON-RPC surface):

NETEXPERT_HTTP_PORT=3100 netexpert-mcp

POST http://127.0.0.1:3100/mcp (tools/list, tools/call)

GET http://127.0.0.1:3100/health (liveness)

Try it in 30 seconds

Once wired into your client, try:

1. "Am I exposed?" → the client calls sec.exposure — listening ports × firewall state × a risky-port knowledge base, reported as Findings.
2. "What's on my network?" → lan.devices — ARP inventory enriched with IEEE-OUI vendor names and PTR hostnames.
3. "Is my DNS lying to me?" → dns.hijackcheck — known-good domains via your system resolver vs trusted DoH; mismatch ⇒ Finding{severity:high}.
4. "Is my WiFi any good?" → wifi.health — RSSI quality bands, channel overlap, band mismatch — interpreted, with next steps.

Why it exists

Existing network MCP servers are either deprecated Python packages, wrappers that demand Nmap, or router-config tools for enterprises. None of them answer the home-lab questions:

Design guarantees

• One envelope. Every tool returns the same JSON shape (ok, backend, data, warnings / closed-set error.code + actionable hint) — no raw netsh or ip output ever reaches the model.
• Platform-normalized. Same field names on Windows, Linux, and macOS; platform dispatch lives below the service layer.
• Bounded everything. Port caps, host caps, byte caps, timeouts, and token-bucket rate limits are enforced in code — never left to the model's judgment.
• No shell, ever. All subprocesses spawn via arg arrays (execFile-style); all inputs are zod-validated before touching the OS. No raw sockets, no Npcap, no Python.
• Read-only by default. The one mutating tool (lan.wol) uses a dry-run plan + single-use, 10-min-TTL confirmToken — parameters frozen at plan time.
• Capability honesty. Tools report *which backend produced the data* (backend: "tcp-connect", not a fake "ping"); net.health self-describes what works on this host, with install hints for what doesn't.
• No telemetry. No phone-home — except the three tools that are *about* the internet (net.publicip, sec.speedtest, DoH in dns.hijackcheck), which you invoked explicitly.

Tool catalog (31)

net.* — connectivity

dns.* — name resolution

lan.* — devices & inventory

wifi.* — link health

sec.* — host posture

Configuration (all optional)

~/.netexpert-mcp/config.json — sane defaults, so zero-config first run:

{

"defaults": { "pingCount": 4, "traceMaxHops": 20 }, "resolvers": { "trusted": ["1.1.1.1", "8.8.8.8"], "dohUrl": "https://cloudflare-dns.com/dns-query" }, "caps": { "portscan": { "maxPorts": 256 }, "sweep": { "maxHosts": 1024 } }, "rate": { "sweep": 30, "portscan": 10, "speedtest": 60, "httpCheck": 2 }, "nmap": { "enabled": false } // deep scans are opt-in by design }

Invariants:

• caps are ceilings — tool inputs may go lower, never higher
• env overrides via NETEXPERT_*: NETEXPERT_MCP_CONFIG (config path), NETEXPERT_HTTP_PORT, NETEXPERT_WIFI_IF (linux wlan iface)
• no credentials ever — any config key containing password/token/secret/credential is rejected at load

Optional extras:

• nmap deep scans — install nmap (winget install Insecure.Nmap / sudo apt install nmap), then set "nmap": { "enabled": true } in config. Absence just produces an install hint, never a crash.
• OUI vendor db — ships inside the package; never fetched at runtime.

Monitoring without a daemon

netexpert stays request/response; recurring checks are your MCP client's job:

New-device tripwire   lan.newdevices    every 15 min   fire on Finding[] beyond the info baseline

Gateway reachability net.ping every 60 s fire on lossPct > 0 DNS integrity dns.hijackcheck hourly fire on sev=high WiFi degradation wifi.health every 10 min fire on severity ≥ med

AI usage — docs/persona.md

The server provides hands; the persona provides judgment. The rule pack in docs/persona.md gives your AI client:

1. a triage ladder (link → ARP → IP/DNS → port → app — always state which layer exonerated/implicated),
2. baselines for "suspicious" (new MAC with no vendor match, RFC1918 host on 445/3389 that isn't the NAS, resolver ≠ DoH, ARP flapping),
3. the Finding format — every answer ends with the concrete next tool call, never a data dump.

Development

git clone https://github.com/Omodaka9375/netexpert-mcp.git

cd netexpert-mcp pnpm install

pnpm typecheck # strict TS (Kai/Claude Code runs this after edits) pnpm test # 50 fixture-driven tests (fake runner, zero real network in units) pnpm build # → dist/ pnpm smoke # build → stdio → tools/list → net.health pnpm smoke:http # HTTP transport check node scripts/gen-oui.mjs # regenerate the OUI db (rarely needed)

Project layout:

src/

exec/ LocalExecutor (execFile, arg arrays) + per-platform CommandMaps (win32/linux/darwin) parse/ pure parsers (arp, ping, traceroute, netsh, iw, nmap -oG) — fixture-tested services/ coreService dnsService lanService wifiService secService nmapService safety/ caps.ts (bounds + token-bucket rate limiter) · confirm.ts (dry-run/confirmToken) data/ oui.json (40k IEEE OUI entries, committed) mcp/ toolset.ts (31 tools, zod inputs) · createServer.ts scripts/ gen-oui.mjs · smoke.mjs · http-smoke.mjs docs/ persona.md · index.html (the docs page) tests/ fixtures/ + 50 tests across 6 files

License: MIT — see LICENSE. npm: netexpert-mcp · MCP registry: io.github.Omodaka9375/netexpert-mcp Source & issues: GitHub