OpenWrt Network Diagnostics MCP
Provides read-only network diagnostics for OpenWrt routers, including system snapshots, config state inspection, DNS tracing, client observation, flow inspection, bounded packet capture, subscription status, log reading, and snapshot comparison.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenWrt Network Diagnostics MCP Troubleshoot my network, start with a snapshot and inspect flows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 checknpm run check 会编译项目并运行 Node.js 内置测试。构建输出位于 dist/,不提交到 Git。
启动
$env:MIHOMO_SECRET = Read-Host "Mihomo secret" -MaskInput
npm run build
npm startMCP 使用 stdio:stdout 只承载协议,审计摘要写入 stderr。正常退出会关闭 Mihomo SSH 隧道。
Codex 注册与验证步骤见 Codex 客户端配置示例。
Agent 取证流程
先调用
snapshot_network建立系统、接口、路由、防火墙与能力基线。默认detail=summary;只有需要完整但仍有界的规范化证据时才使用detail=full。按问题范围调用
inspect_config_state或trace_dns。把 generated config 与 runtime state 视为不同来源。用户准备复现时调用
observe_client,窗口为 5–60 秒。双栈设备可显式提供client_ipv6;MCP 不自动认定 IPv4/IPv6 属于同一设备。已知客户端与目标后调用
inspect_flow,关联 DNS、Mihomo、同地址族转发路由、nftables 与严格过滤的 conntrack;必要时可显式使用detail=full。现有证据不足时由 Agent 显式调用
capture_flow。默认 30 秒,接口自动按客户端回程路由选择;同一时间只运行一个长观察或抓包。修改前后分别运行
snapshot_network,再用compare_snapshots计算字段差异。
MCP 不返回 verdict、confidence、root cause 或修复建议。没有捕获到连接表示证据缺失,不表示静态规则实际命中或未命中。
工具
工具 | 返回的路由器侧事实 |
| 系统、网络、服务、监听、路由、nftables 与能力快照 |
| Nikki 生成配置摘要、文件身份、Mihomo runtime 与 provider 摘要 |
| router-local、Mihomo、LAN listener、bootstrap DNS 与地址属性 |
| 指定客户端窗口内的新连接、Mihomo 日志与 conntrack 事件 |
| 指定流的 DNS、实际代理链、转发路由、nftables 与 conntrack |
| 有界 tcpdump 包元数据和 TCP/UDP/DNS 机械摘要 |
| Nikki 缓存文件身份、更新时间与 Mihomo provider 状态 |
| 按来源、窗口、条数和文本过滤的脱敏日志 |
| 当前 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 进程内,进程退出后失效。
Available Tools
9 toolscapture_flowCapture bounded packet metadataCRead-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 snapshotsARead-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 stateARead-only
Compare whitelisted Nikki generated startup fields with Mihomo runtime General state and provider summaries.
Inputs: no named parameters.
inspect_flowInspect one target flowBRead-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 stateARead-only
Return safe Nikki cache metadata and Mihomo provider summaries without URLs or credentials.
Inputs: no named parameters.
observe_clientObserve one LAN clientBRead-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 logsARead-only
Read filtered and redacted OpenWrt, Nikki, or newly observed Mihomo logs.
Inputs: source (required), contains, duration, max_records.
snapshot_networkSnapshot OpenWrt network stateARead-only
Collect a bounded router-side network snapshot and retain it in memory for later comparison.
Inputs: detail.
trace_dnsCollect router-side DNS evidenceARead-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
Scored across 9 tools
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).
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.
9 tools is well-scoped for a specialized network diagnostics server, covering both data collection and analysis without unnecessary bloat or missing core functionality.
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
Related MCP Connectors
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Network, domain and website diagnostics for AI clients via MCP.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server providing network diagnostic tools for AI agents, including connectivity testing, batch operations, local network info, and pcap analysis.346MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for Linux and macOS system administration, diagnostics, and troubleshooting, supporting remote SSH execution and multi-host management.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for managing OPNsense firewalls, providing read-only tools for firewall rules, aliases, interface statistics, and gateway status with multi-instance support.MIT
- AlicenseNot gradedqualityDmaintenanceAn 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