Netexpert Mcp

io.github.Omodaka9375Published by GitHub account Omodaka9375v0.1.3Updated Nov 1, 2026

Cross-platform local-network diagnostics & security-posture MCP server — 31 tools.

VerifiedSTDIODesktop onlyLocation & LifestyleCloud & InfrastructureSecurity & Monitoring

Overview

AI-generated overview

Local-network diagnostics and host security-posture MCP server with 31 tools for connectivity, DNS, LAN inventory, WiFi health and exposure checks.

What you can do
  • Check connectivity and reachability: ping, traceroute, HTTP timing, port checks and bounded port scans, TLS certificate details, public IP.
  • Resolve and compare DNS: lookups, reverse PTR, system resolvers, propagation diffs and hijack checks against trusted DoH.
  • Inventory the LAN: interfaces, gateway, ARP cache, subnet sweeps, device lists with vendor and hostname enrichment, snapshots and new-device diffs.
  • Assess WiFi link health: current link status, nearby access-point survey, and interpreted findings on signal, channel overlap and band mismatch.
  • Review host posture: active connections, listening ports, firewall state, an exposure report over risky ports, and a bounded speed test.
  • Wake a…
When to use it
Useful for home-lab and small-office troubleshooting where you want an assistant to answer questions like what devices are on the network, whether the WiFi link is healthy, whether this machine is exposed, or why a host is unreachable. It suits read-only diagnostics on the local host and LAN rather than enterprise router configuration.
Requirements
Runs as a local stdio process, typically via npx or a global npm install, so Node.js is needed. No config file, environment variables or credentials are required on first run. Optional settings: NETEXPERT_MCP_CONFIG for a config path, NETEXPERT_HTTP_PORT to also serve a loopback HTTP endpoint, NETEXPERT_WIFI_IF for the Linux wlan interface. Optional nmap deep scans need the nmap binary and nmap.enabled in config.
Before you install
Tools probe the local network and host: subnet sweeps, port scans and listener enumeration can be intrusive or against policy on networks you do not own. lan.wol sends a wake packet after a confirmation token, so it is the one mutating action. Three tools contact the internet (public IP lookup, speed test, DoH comparison in the DNS hijack check). Optional nmap deep scans are opt-in and restricted to private ranges. Config keys resembling passwords, tokens or secrets are rejected at load.

Installation

In SourceWeft

  1. Open Netexpert Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

bash
# run once, on demand (no install)npx -y netexpert-mcp
# or install globallynpm install -g netexpert-mcpnetexpert-mcp

Wire it into your MCP client (stdio):

jsonc
{  "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):

bash
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:

Questionnetexpert answer
What devices are on my network — anything new?lan.devices builds an inventory (ARP ∪ sweep, OUI vendor, PTR hostname); lan.newdevices diffs it against snapshots and emits findings
Is my WiFi actually good?wifi.health interprets RSSI bands, channel overlap, and band mismatch — with concrete next steps, not raw numbers
Is this machine exposed?sec.exposure cross-references listening ports with firewall state and a risky-port knowledge base
Is my DNS lying to me?dns.hijackcheck compares your system resolver against trusted DoH for known-good domains
Why is X unreachable?Layered triage — link → ARP → routing/DNS → port → app (docs/persona.md)

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

ToolWhat it does
net.healthVersion, platform, capability matrix (which backends exist on this host, with install hints)
net.pingICMP loss/latency stats; honest TCP-connect fallback when ping is unavailable
net.traceTraceroute hops, normalized across tracert/traceroute/tracepath
net.httpcheckGET/HEAD with timing split: dns / connect / ttfb / total
net.portcheckSingle TCP connect — open/closed + latency
net.portscanBounded connect scan (≤256 ports, default top-20 common)
net.sslTLS cert: subject, SANs, issuer, chain, days-left, expiry grade
net.publicipYour public IPv4 + ASN/org (ipify → ipinfo fallback)
net.deepscanOptional nmap adapter — opt-in only: requires the binary and nmap.enabled in config; RFC1918 targets only

dns.* — name resolution

ToolWhat it does
dns.lookupA/AAAA/CNAME/MX/TXT/NS/SRV/PTR with optional nameserver override
dns.reversePTR names for an IP
dns.resolversWhich DNS servers the OS actually uses (per-platform)
dns.propagationSame record at system + trusted resolvers + DoH — diff table
dns.hijackcheckThe killer check: known-good domains via system vs trusted DoH; mismatch or NXDOMAIN ⇒ Finding{sev:high}

lan.* — devices & inventory

ToolWhat it does
lan.interfacesNICs: name, MAC, addresses, type, virtual flag
lan.gatewayDefault gateway + interface + local subnet CIDR
lan.arpParsed neighbor cache, stale entries filtered
lan.sweepPing-probe an RFC1918 subnet (≤1024 hosts, rate-limited 1/30s) → live set
lan.devicesInventory: ARP ∩ RFC1918, enriched with vendor (40k-entry IEEE OUI db) + PTR hostname
lan.hostnameAll known names for an IP: PTR + NetBIOS (win)
lan.snapshotSave device inventory to dated snapshots; or list them
lan.newdevicesDiff live vs baseline ⇒ findings (new MAC, MAC-changed-for-IP); first run auto-saves a baseline
lan.wolWake-on-LAN magic packet — dry-run plan → confirmToken → one UDP broadcast

wifi.* — link health

ToolWhat it does
wifi.statusCurrent link: SSID, BSSID, band, channel, RSSI, PHY rate, quality 0–100
wifi.networksNearby AP survey with band inference
wifi.healthInterpretation: RSSI bands (≥−50 … <−78 unusable), 2.4 GHz channel overlap, band mismatch, low PHY rate — each a Finding with the next tool call

sec.* — host posture

ToolWhat it does
sec.connectionsActive sockets with owning PID
sec.listeningListeners per process; flags 0.0.0.0/:: exposures
sec.firewallGet-NetFirewallProfile / ufw→nft / socketfilterfw
sec.exposureHeadline report: exposed listeners × firewall state × risky-port table (445, 3389, 23, 135–139, 5357, 5900) ⇒ Finding[]
sec.speedtestBounded Cloudflare download; reports a lower bound instead of failing on slow links

Configuration (all optional)

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

jsonc
{  "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:

text
New-device tripwire   lan.newdevices    every 15 min   fire on Finding[] beyond the info baselineGateway reachability  net.ping <gw>    every 60 s      fire on lossPct > 0DNS integrity         dns.hijackcheck   hourly          fire on sev=highWiFi 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

bash
git clone https://github.com/Omodaka9375/netexpert-mcp.gitcd netexpert-mcppnpm 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.healthpnpm smoke:http     # HTTP transport checknode scripts/gen-oui.mjs   # regenerate the OUI db (rarely needed)

Project layout:

text
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.tsscripts/       gen-oui.mjs · smoke.mjs · http-smoke.mjsdocs/          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

Source: README.md at commit f967097

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.3LatestOct 18, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts