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 分