keenetic-mcp

keenetic-mcp

通过 Claude、Codex、Cursor 或任何 MCP Agent 控制你的 Keenetic 路由器。

用日常语言向你的 Agent 询问网络情况。无需 USB 闪存盘，无需 Entware， 路由器上也无需安装任何东西。

> who is using the most bandwidth right now?

  Three devices are active. Sorted by traffic:

  work-laptop      wifi:HomeNet   -46 dBm    7.7 GB down
  living-room-tv   wired:Home                3.2 GB down
  hallway-camera   wifi:HomeNet   -48 dBm    5.4 MB down

  The laptop is on the 2.4 GHz radio at -46 dBm, which is a strong
  signal, so the throughput is not a coverage problem.

> block the camera until tomorrow morning

  Blocked hallway-camera (02:00:00:00:00:14).

  Applied to the running configuration and verified, but NOT saved.
  A reboot discards it. Backup taken before the change:
  ~/Library/Application Support/keenetic-mcp/backups/…txt

  Say the word and I will make it permanent, or leave it and it
  reverts on the next restart.

为什么选择它

• 路由器上无需安装任何东西。 它通过你的 局域网与路由器自带的 HTTP API 通信。无需 USB 驱动器、Entware，也无需修改固件。
• 适用于任何 Keenetic。 工具集会根据你的具体型号和固件实际支持的功能进行调整。
• 安全性融入设计。 除非你提出要求，否则不会保存更改；首次更改前会先创建备份；每项更改都会读回并验证，然后才报告已完成。
• 可设为只读。 只需一个标志，Agent 在物理层面上就无法更改任何内容。

安装

Claude Code

/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keenetic

然后在终端中运行设置向导：

npx -y keenetic-mcp init

Codex

codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp init

这会同时安装技能和服务。若只安装服务：

codex mcp add keenetic -- npx -y keenetic-mcp

其他情况

{
  "mcpServers": {
    "keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
  }
}

向导会根据默认网关找到你的路由器，确认它确实是 Keenetic，验证密码，并将密码保存到操作系统的密钥链中。设置文件中只会保存地址和登录名。

更喜欢使用环境变量？KEENETIC_HOST、KEENETIC_USER 和 KEENETIC_PASSWORD 会覆盖所有其他设置，这正适合在容器中使用。

功能

读取

工具
list_devices	列出所有设备，可按活动、有线、无线或已阻止状态筛选，并按流量或信号排序
get_device	完整查看单台设备：租约、Wi-Fi 速率、策略、计划、流量
list_interfaces	WAN 链路、网桥、接入点、VPN 隧道
get_interface	完整查看单个接口，包括 WireGuard 对等端
get_wifi_status	按频段查看无线电，以及客户端数量
get_internet_status	查看网络连通性，以及未通过的检查项
list_routes	查看路由表，或仅查看默认路由
list_policies	查看用于选择性路由的连接策略
get_system_info	型号、固件、CPU、内存、已安装组件
get_config_state	未保存的更改、谁在何时更改了什么
list_segments	列出所有网桥，以及 Web 界面是否将其列为网段
backup_config	将配置下载到本地文件

更改

工具
update_device	重命名、阻止或允许设备、分配路由策略、计划或优先级
set_interface_state	启用或停用接口
create_segment	创建 Web 界面实际列出的访客或 IoT 网络，可配置 Wi-Fi、DHCP 和可选的 VPN 路由
delete_segment	删除网段及其创建的所有内容
save_config	保存待处理的更改，使其在重启后仍然生效

备用通道

工具
rci_call	调用任意路由器 API 路径，处理上述工具未涵盖的操作

包含的技能

此插件提供四项技能，让 Agent 了解路由器的行为，而不是靠猜测。一个插件目录同时适用于 Claude Code 和 Codex：它们读取不同的清单，但共用相同的技能和服务定义。

• keenetic-rci 介绍路由器的 API 树：哪些路径存在、哪些会返回 100 KB 数据，以及如何从路由器自身的配置中还原命令的准确语法。
• keenetic-safe-changes 介绍变更工作流：路由器的故障安全机制能保护什么、不能保护什么，以及哪些接口会切断你自己的访问。
• keenetic-segments 介绍如何构建路由器能够识别的隔离网络。直观的做法会创建一个运行正常、但永远不会出现在 Web 界面中的访客网络，因为网段由 VLAN 支持，而大家总会漏掉 VLAN 这一步。
• keenetic-troubleshoot 是一份按顺序排列的诊断手册，适用于“互联网断了”“Wi-Fi 很差”和“某台设备无法连接”等问题。

安全

• 除非你要求，否则不会保存任何更改。 更改会应用到当前运行配置中，并在重启时丢弃，除非调用 save_config。服务不会自行调用它。
• 首次变更前会自动创建备份。
• 每项更改都会经过验证。 路由器有时会静默接受错误命令而不做任何更改，因此每次写入后都会读取并比对，确认无误后才报告成功。
• 只读模式确实是只读的。 使用 --read-only 时，写入工具根本不会注册，而不是注册后再拒绝调用，因此 Agent 完全看不到这些工具。
• 密码保存在系统密钥链中，而不是配置文件中，也绝不会出现在日志或工具响应中。
• 仅限局域网。 不使用云服务或遥测，也不会连接路由器以外的任何目标。

各平台上密码的存储位置，以及如何私下报告问题，请参阅 SECURITY.md。

支持的路由器

此工具使用的 API RCI 是 KeeneticOS 的标准组成部分，并非昂贵型号的专属功能，因此适用于全系列路由器。已在 运行 KeeneticOS 5.1.3 的 Keenetic Ultra (KN-1811) 上验证。

当前 5.1 分支支持的型号：Giga (KN-1010)、Hero (KN-1011、KN-1012)、Start 和 Starter (KN-1111、KN-1112、KN-1121)、Air 和 Explorer (KN-1613、KN-1621)、Extra 和 Carrier (KN-1713、KN-1714、KN-1721)、Ultra 和 Titan (KN-1810、KN-1811、KN-1812)。运行 4.x 及更早版本的旧硬件也支持 RCI；工具集会根据各路由器实际具备的组件进行调整。

工作原理

Keenetic 路由器通过 HTTP 暴露 RCI，这是一份命令行树的 JSON 镜像。此服务使用路由器的质询-响应机制进行身份验证，在 Agent 提问期间维持同一会话，并调整答案的格式以适应模型的上下文：仅原始接口列表就有 32 KB，而 NAT 表超过 100 KB。

RCI 没有完整一致的公开文档，因此 docs/rci-api.md 是构建过程中整理的笔记，涵盖身份验证握手、现有路径、常见陷阱，以及如何从路由器本身还原命令语法。

开发

npm install
npm test          # no router required
npm run typecheck
npm run build

检出代码时显示的版本为 0.0.0-dev，因为源代码中没有任何地方记录版本。要指定其他版本，请在仓库根目录的 .env 文件中设置 KEENETIC_MCP_VERSION；同一文件也可以存放 KEENETIC_HOST 和 KEENETIC_PASSWORD，这样就不必导出它们。真实环境变量的优先级始终高于该文件，已安装的副本则不会读取该文件。

测试使用从真实路由器采集并经过脱敏处理的固件数据。要刷新这些数据，并对自己的设备运行只读冒烟测试：

KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smoke

固件数据会以确定性方式匿名化，且有一项测试会扫描整个仓库，查找任何疑似真实 MAC 地址、私有 IP 或密钥的内容。

设置向导会从终端读取密码，单元测试无法访问这部分功能：通过管道传入输入会走完全不同的代码路径。此部分通过驱动真实伪终端的脚本进行检查，因此需要终端，无法在 CI 中运行：

KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.exp

发布

发布只需要打一个标签，不需要做其他操作。无需提交版本变更，因为仓库中没有需要修改的版本：package.json 中的版本为 0.0.0-dev，插件清单中完全没有版本，发布工作流会在发布前立即将标签写入 package.json，但不会提交该修改。

git tag v0.2.2 && git push origin v0.2.2

工作流会拒绝不符合版本命名规则的标签，测试也会拒绝写入了版本的代码树，因此两者永远不会不一致。插件会固定使用 keenetic-mcp@^0，仅跟踪主版本号，计划在 1.0 时修改一次。

许可证

MIT