OpenWrt LuCI HTTP MCP

标准 OpenWrt LuCI Web 界面的只读 MCP 表达，通过 LuCI 原生 POST /ubus/ JSON-RPC 接口读取状态和运行其诊断页中的固定命令，不使用 SSH，也不在路由器上安装代理。

当前版本：0.4.0。以 OpenWrt 25.12.3 / LuCI openwrt-25.12 为 ground truth；可选方法不存在时返回明确的 supported: false，不会把权限或认证错误误报为不支持。

安全范围

• 使用现有 LuCI root 登录，不创建新账户。

• 密码只从环境变量读取，不写入源码或日志。

• 不注册任意 ubus 调用、任意 shell、重启、固件升级或 UCI 写入工具。

• ip、nft、dmesg、软件目录和网络诊断只执行代码中写死的程序与参数结构；不经过 shell。

• 网络诊断只允许经过校验的目标，Ping 次数、Traceroute 超时和跳数均不可由调用者改变。

• 返回给模型前隐藏密码、PSK、community、令牌、会话标识、私钥、HTTP Authorization 和 URL 内嵌认证材料。

• 单次 LuCI 响应限制为 2 MiB，单个 MCP 结果限制为 256 KiB；超限返回有效 JSON 错误而非截断内容。

这只是 Demo。root 密码通过普通 HTTP 发送时没有传输加密，只应在可信 LAN 中临时测试。长期使用应开启 LuCI HTTPS，并改为受限 rpcd 账户。

Related MCP server: OpenWrt MCP Controller

环境要求

• Node.js 20 或更高版本

• OpenWrt/LuCI 可通过局域网访问

• uhttpd-mod-ubus 与 rpcd 正常工作

安装

cd C:\absolute\path\to\openwrt-luci-mcp-demo
npm install

不要复制 .env.example 后把真实密码提交到 Git。推荐直接在 MCP 客户端的进程环境中设置变量：

OPENWRT_URL=http://router.example.invalid
OPENWRT_USERNAME=root
OPENWRT_PASSWORD=<LuCI root 密码>
OPENWRT_ALLOW_INSECURE_HTTP=1

OPENWRT_ALLOW_INSECURE_HTTP=1 是显式风险确认。若 LuCI 已启用 HTTPS，请使用 https://... 并删除该变量。

运行

npm start

stdio 是 MCP 协议通道；程序日志只写入 stderr。通常由 MCP 客户端启动本程序，而不是手动交互。

参考 mcp-config.example.json 配置客户端，并把其中的 Node 与 src/index.mjs 路径改为绝对路径。

工具

• router_capabilities

• router_luci_pages

• router_system_info

• router_interfaces

• router_interface_details

• router_routing_config

• router_network_device

• router_port_status

• router_vlan_config

• router_dhcp_leases

• router_dhcp_config

• router_dns_config

• router_known_hosts

• router_wifi_overview

• router_wifi_details

• router_wifi_clients

• router_services

• router_processes

• router_realtime_stats

• router_routes

• router_neighbors

• router_firewall_status

• router_firewall_config

• router_nftables_rules

• router_wifi_scan

• router_logs

• router_connections

• router_storage

• router_packages

• router_package_catalog

• router_time_status

• router_system_settings

• router_network_diagnostics

• router_network_consistency

• router_run_diagnostic

• router_security_audit

• router_client_summary

每个工具同时返回兼容的文本 JSON 和 MCP structuredContent。路由、DHCP/DNS、Firewall、VLAN、大型规则和软件目录使用 offset、limit 分页。

v0.4.0 增加 LuCI 网络配置控制面的只读表达：静态路由与策略规则、dnsmasq/odhcpd、DNS 记录、Firewall 关系、DSA/swconfig VLAN、基础 System 设置，以及配置与运行态一致性检查。工具只读取已提交配置；不会读取其他 LuCI 会话中尚未应用的 UCI 暂存变更。

router_network_diagnostics 只分析现有状态。router_run_diagnostic 对应 LuCI Network → Diagnostics 页面，会产生 Ping、Traceroute 或 DNS 流量，但不修改配置。router_package_catalog 只调用 LuCI package manager 的 list-installed 和 list-available，不更新软件源。

LuCI 页面覆盖

同一矩阵可由 router_luci_pages 读取。Switch/VLAN 仅在 DSA bridge-vlan 或旧 swconfig 配置存在时支持。WireGuard、SQM、UPnP 等可选 LuCI 应用不在 v0.4.0 范围内。

没有提供以下能力：

uci.set / uci.delete / uci.apply
任意 file.exec / file.write / file.remove
system.reboot
luci.setPassword
hostapd.*.del_client

测试

27 项测试使用本机模拟 /ubus/ 服务，不连接或修改真实路由器：

npm test

一次性真实连接检查

在 PowerShell 中使用安全密码提示，不把密码写入文件：

$secure = Read-Host 'LuCI root password' -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
try {
  $env:OPENWRT_PASSWORD = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
  $env:OPENWRT_URL = 'http://router.example.invalid'
  $env:OPENWRT_USERNAME = 'root'
  $env:OPENWRT_ALLOW_INSECURE_HTTP = '1'
  npm run check:live
}
finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
  Remove-Item Env:OPENWRT_PASSWORD -ErrorAction SilentlyContinue
}

该检查只调用 system.board、system.info 和 luci.getVersion。

目标路由器核验范围

通过已登录 LuCI 页面确认以下模块在目标路由器上存在且可正常读取，没有出现 RPC access denied：

• 活动 IPv4/IPv6 路由、策略规则和邻居表

• nftables fw4 运行时状态

• 系统日志

• Wi-Fi 信道分析

• 软件包管理器

• 网络诊断

• 静态路由、DHCP/DNS 与 Firewall 配置

• DSA/bridge-vlan 与基础 System 设置

实现方法与 OpenWrt 25.12 使用的 LuCI/rpcd 接口保持一致；若将来更换固件或裁剪 LuCI 软件包，可调用 router_capabilities 和 router_luci_pages 核对实际支持情况。