Netexpert Mcp

io.github.Omodaka9375由 GitHub 帳號 Omodaka9375 發布v0.1.3更新於 Nov 1, 2026

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

已驗證STDIO僅桌面位置與生活雲端與基礎設施安全與監控

概覽

AI 產生的概覽

本機網路診斷與主機安全態勢 MCP 伺服器，提供 31 個工具，涵蓋連線品質、DNS、區域網路裝置、WiFi 健康度與暴露面檢查。

可以做什麼
  • 檢查連線與可達性：ping、路由追蹤、HTTP 分段計時、連接埠探測與有上限的連接埠掃描、TLS 憑證資訊、公用 IP。
  • 解析並比對 DNS：各類記錄查詢、反向 PTR、系統解析器、傳播差異，以及對照可信 DoH 的劫持檢查。
  • 盤點區域網路：網路卡、閘道、ARP 快取、子網掃描、含廠商與主機名稱補齊的裝置清單、快照與新裝置差異。
  • 評估 WiFi 連線：目前連線狀態、鄰近基地台掃描，以及訊號、頻道重疊與頻段不符的解讀結論。
  • 檢視主機態勢：作用中連線、監聽連接埠、防火牆狀態、針對高風險連接埠的暴露報告，以及有上限的測速。
  • 透過試跑計畫與一次性確認權杖，向區域網路內主機送出喚醒封包。
適用情境
適合家用實驗室或小型辦公網路的排障：讓助理回答網路上有哪些裝置、WiFi 連線是否健康、本機是否暴露、某台主機為何連不上等問題。它著重本機與區域網路的唯讀診斷，而非企業級路由器設定。
執行需求
以本機 stdio 程序執行，通常透過 npx 或全域 npm 安裝，因此需要 Node.js。首次執行不需設定檔、環境變數或憑證。選用設定：NETEXPERT_MCP_CONFIG 指定設定檔路徑，NETEXPERT_HTTP_PORT 額外提供回送位址的 HTTP 端點，NETEXPERT_WIFI_IF 指定 Linux 無線網路介面。選用的 nmap 深度掃描需要 nmap 程式並在設定中啟用 nmap.enabled。
安裝前請注意
工具會探測本機網路與主機：子網掃描、連接埠掃描與監聽連接埠列舉可能具侵入性，在非自有的網路上可能違反規定。lan.wol 在確認權杖後送出喚醒封包，是唯一會改變狀態的動作。有三個工具會連上網際網路（公用 IP 查詢、測速、DNS 劫持檢查中的 DoH 比對）。選用的 nmap 深度掃描須手動開啟且僅限私有位址範圍。設定中類似密碼、權杖或密鑰的鍵會在載入時被拒絕。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Netexpert Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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

來源：README.md，提交 f967097

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.1.3最新Oct 18, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分