Skip to main content
Glama
OpenWrt Network Diagnostics MCP

OpenWrt Network Diagnostics MCP

by gomixo

OpenWrt Network Diagnostics MCP

面向 OpenWrt、Nikki 与 Mihomo 的只读诊断 MCP。它向 Agent 提供路由器侧 Observation、机械 Correlation 和证据缺口;故障判断与修复决策仍由 Agent 结合客户端证据完成。

0.2 只支持已经实机验证的组合:FriendlyElec NanoPi R5S、ImmortalWrt 25.12、Nikki、Mihomo 与 firewall4/nftables。所有 Evidence bundle 使用 schema_version: 2。

准备

  • Windows 工作站安装 Node.js 24 和 OpenSSH Client。

  • SSH config 存在可免交互登录的 Host openwrt。

  • 路由器安装 conntrack、tcpdump、yq、ip、nft 与 ubus。

  • Mihomo external controller 在路由器 loopback 的 9090 端口可用。

  • MIHOMO_SECRET 只通过 MCP 子进程环境变量提供。

SSH config 示例:

Host openwrt
  HostName 192.0.2.1
  User root
  IdentityFile C:/Users/<you>/.ssh/openwrt_ed25519

完成标准:以下命令输出设备信息且不要求密码。

ssh -o BatchMode=yes openwrt "ubus call system board"

Related MCP server: Linux MCP Server

安装与检查

cd D:\Workspace\OpenWrt-MCP
npm ci
npm run check

npm run check 会编译项目并运行 Node.js 内置测试。构建输出位于 dist/,不提交到 Git。

启动

$env:MIHOMO_SECRET = Read-Host "Mihomo secret" -MaskInput
npm run build
npm start

MCP 使用 stdio:stdout 只承载协议,审计摘要写入 stderr。正常退出会关闭 Mihomo SSH 隧道。

Codex 注册与验证步骤见 Codex 客户端配置示例。

Agent 取证流程

  1. 先调用 snapshot_network 建立系统、接口、路由、防火墙与能力基线。默认 detail=summary;只有需要完整但仍有界的规范化证据时才使用 detail=full。

  2. 按问题范围调用 inspect_config_state 或 trace_dns。把 generated config 与 runtime state 视为不同来源。

  3. 用户准备复现时调用 observe_client,窗口为 5–60 秒。双栈设备可显式提供 client_ipv6;MCP 不自动认定 IPv4/IPv6 属于同一设备。

  4. 已知客户端与目标后调用 inspect_flow,关联 DNS、Mihomo、同地址族转发路由、nftables 与严格过滤的 conntrack;必要时可显式使用 detail=full。

  5. 现有证据不足时由 Agent 显式调用 capture_flow。默认 30 秒,接口自动按客户端回程路由选择;同一时间只运行一个长观察或抓包。

  6. 修改前后分别运行 snapshot_network,再用 compare_snapshots 计算字段差异。

MCP 不返回 verdict、confidence、root cause 或修复建议。没有捕获到连接表示证据缺失,不表示静态规则实际命中或未命中。

工具

工具

返回的路由器侧事实

snapshot_network

系统、网络、服务、监听、路由、nftables 与能力快照

inspect_config_state

Nikki 生成配置摘要、文件身份、Mihomo runtime 与 provider 摘要

trace_dns

router-local、Mihomo、LAN listener、bootstrap DNS 与地址属性

observe_client

指定客户端窗口内的新连接、Mihomo 日志与 conntrack 事件

inspect_flow

指定流的 DNS、实际代理链、转发路由、nftables 与 conntrack

capture_flow

有界 tcpdump 包元数据和 TCP/UDP/DNS 机械摘要

inspect_subscriptions

Nikki 缓存文件身份、更新时间与 Mihomo provider 状态

read_logs

按来源、窗口、条数和文本过滤的脱敏日志

compare_snapshots

当前 MCP 进程内两个快照的字段级差异

实机 smoke test

smoke test 会从指定 LAN 客户端建立真实 Google HTTPS/TLS 流量,验证九个工具、同流量关联、脱敏以及长任务清理。

$env:MIHOMO_SECRET = Read-Host "Mihomo secret" -MaskInput
npm run smoke:live -- 192.0.2.20

完成标准:进程退出码为 0,九个工具均返回 schema v2;必需 Observation 成功,不支持的 bootstrap endpoint 被明确标记;summary 小于 full;并输出 secret_leaked: false。

安全边界

  • 只执行固定、校验后的 SSH 命令与 Mihomo GET 请求。

  • 不提供任意 shell、原始 BPF、配置写入、服务重启、策略切换、连接删除或软件安装。

  • 不返回订阅 URL、认证字段、节点凭据、私钥、完整配置或 PCAP。

  • 抓包不落盘,最多 60 秒、200 条包元数据、snaplen 256,并受字节上限和取消信号约束。

  • 快照只保存在当前 MCP 进程内,进程退出后失效。

更完整的需求与边界见 0.1 实施规格和 0.2 开发规格。

Available Tools

9 tools
capture_flowCapture bounded packet metadataC
Read-only

Run an explicitly requested, non-persistent packet capture using a generated restricted filter.

Inputs: client_ip (required), port, domain, duration, +4 more.

compare_snapshotsCompare two in-memory network snapshotsA
Read-only

Return mechanically computed field changes between snapshots from the current MCP process.

Inputs: after_id (required), before_id (required).

inspect_config_stateInspect Nikki and Mihomo configuration stateA
Read-only

Compare whitelisted Nikki generated startup fields with Mihomo runtime General state and provider summaries.

Inputs: no named parameters.

inspect_flowInspect one target flowB
Read-only

Correlate live Mihomo, routing, aggregated nftables, and conntrack evidence for a client and destination.

Inputs: client_ip (required), port, detail, domain, +3 more.

inspect_subscriptionsInspect subscription control-plane stateA
Read-only

Return safe Nikki cache metadata and Mihomo provider summaries without URLs or credentials.

Inputs: no named parameters.

observe_clientObserve one LAN clientB
Read-only

Observe bounded Mihomo connection/log activity and conntrack state associated with one client address.

Inputs: client_ip (required), duration, client_ipv6.

read_logsRead bounded router-side logsA
Read-only

Read filtered and redacted OpenWrt, Nikki, or newly observed Mihomo logs.

Inputs: source (required), contains, duration, max_records.

snapshot_networkSnapshot OpenWrt network stateA
Read-only

Collect a bounded router-side network snapshot and retain it in memory for later comparison.

Inputs: detail.

trace_dnsCollect router-side DNS evidenceA
Read-only

Compare OpenWrt and Mihomo DNS observations, generated DNS settings, Fake-IP addresses, and listeners.

Inputs: domain (required), qtype, server.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools target clearly distinct diagnostic aspects (snapshot, config, DNS, client, flow, capture, subscriptions, logs). The only potential overlap is between observe_client and inspect_flow, but their descriptions clarify different scopes (client-level vs. flow-level).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., snapshot_network, inspect_config_state, capture_flow). Even with repeated verbs like 'inspect', the nouns clearly differentiate the tools.

    Tool Count5/5

    9 tools is well-scoped for a specialized network diagnostics server, covering both data collection and analysis without unnecessary bloat or missing core functionality.

    Completeness4/5

    The tool set covers major diagnostic workflows: snapshots, config comparison, DNS tracing, client observation, flow inspection, packet capture, subscription metadata, and logs. Minor gaps exist such as an explicit connectivity test or snapshot management, but core capabilities are solid.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for Linux and macOS system administration, diagnostics, and troubleshooting, supporting remote SSH execution and multi-host management.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing OPNsense firewalls, providing read-only tools for firewall rules, aliases, interface statistics, and gateway status with multi-instance support.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for comprehensive OPNsense firewall management, enabling AI assistants to manage firewall rules, NAT, VLANs, and network diagnostics, plus execute SSH/CLI commands. Supports safety modes like read-only and dry-run for safe operation.
      MIT