Keenetic-router-plugin

A plugin (MCP server + skill) that gives an AI agent control over a Keenetic router via RCI — the same API the router's web interface uses. It works directly on the local network, no cloud involved. The MCP server is standalone and works with any MCP client (e.g., Codex), while the skill (domain knowledge about Keenetic for the AI) is only available in the Claude Code plugin ecosystem.

Tested on KeeneticOS 5.0.12. On another model/firmware, specific RCI paths may differ — before getting started, run npm run smoke (read-only, it changes nothing on the router).

What the AI can and cannot do through this plugin

Reading — no confirmation needed, at any time: firmware version, WAN status, list of interfaces, connected devices, Wi-Fi clients, port forwarding, routes, DHCP reservations, VPN interfaces, full configuration export (export_config).

Changes — only if the AI explicitly passes confirm: true: changing the Wi-Fi password, enabling/disabling the access point, adding/removing port forwardings, adding/removing routes, binding/unbinding a network to an already configured VPN tunnel, batch applying routes from a .bat file. Without confirm: true, the call is rejected. You can ask the AI to first run it with dryRun: true — it will show what exactly will be sent to the router, changing nothing.

Dangerous operations — additionally require ALLOW_DESTRUCTIVE=true in the server config: rebooting the router. As long as the flag is not enabled, the router cannot be rebooted through the AI, even with confirm: true.

What the plugin cannot do at all (not implemented): creating VPN tunnels from scratch (WireGuard/OpenVPN/IPsec), factory reset, firmware update.

Every write/destructive call (applied, rejected, or failed with an error) is written to audit.log.

Related MCP server: Keenetic NOC MCP

Installation

Requires Node.js 20+.

1. Clone the project and install dependencies:

   npm install
   npm run build

2. Copy .env.example to .env in the same directory and fill it in:

   ROUTER_HOST=192.168.1.1        # LAN-адрес роутера (в свойствах сети — "основной шлюз")
   ROUTER_PORT=80
   ROUTER_LOGIN=имя_пользователя
   ROUTER_PASSWORD=пароль_пользователя
   ALLOW_DESTRUCTIVE=false        # true — разрешить reboot_router

   Instead of .env, the same values can be passed with --env when registering the server — see the below.

3. Check the connection (read-only, it doesn't change anything on the router):

   npm run smoke

   If a request returned an error, your model/firmware has a different RCI path — fix it in src/capabilities/*.ts before working with the AI.

Connecting to Claude Code

As a plugin (recommended — comes with the skill right away):

claude --plugin-dir "<путь-к-проекту>"

For a permanent connection (not just one session), use /plugin install once you put the project into a Git repository or local marketplace.

Server only, without the skill:

claude mcp add --transport stdio --scope user keenetic -- node "<путь-к-проекту>/dist/index.js"

If you haven't created a .env, add your credentials right here:

claude mcp add --transport stdio --scope user \
  --env ROUTER_HOST=192.168.1.1 --env ROUTER_LOGIN=имя_пользователя --env ROUTER_PASSWORD=его_пароль \
  keenetic -- node "<путь-к-проекту>/dist/index.js"

Check the connection with claude mcp list, claude mcp get keenetic or /mcp inside a session.

After that, in the conversation you can write, for example: "show the devices connected to the router" or "change the guest Wi-Fi password".

Connecting to Codex

In ~/.codex/config.toml:

[mcp_servers.keenetic]
command = "node"
args = ["<путь-к-проекту>/dist/index.js"]

Security

The guard model (confirm/dryRun/ALLOW_DESTRUCTIVE) protects against accidental and careless action by the AI. It does not protect the router password itself — if .env or the config falls into the wrong hands, someone can directly log into the router with that password, bypassing the server and all these restrictions.

• export_config is formally read-only, but returns secrets in plain or weakly obfuscated form (password hashes, SSID-PSK, WireGuard parameters) — the same information as behind the "Save" button in the web interface, but now in the conversation with the AI. The tool itself asks the AI to warn you before calling it.

• Create a separate user for the service in the router web interface (System → Users) rather than using admin, where possible. Caveat: some operations (specifically set_wifi_password/set_wifi_enabled) on Keenetic are available only to admin — if you need these, use admin, but with a fresh unique password.

• Don't expose RCI/the web admin panel to the Internet — don't enable remote access, KeenDNS with management access, or a public port forward to the web admin panel for this account. By default, Keenetic is already closed from the outside.

• Restrict access to .env at the OS level (chmod 600 .env on macOS/Linux, or file properties → "Security" on Windows). The file is already in .gitignore.

• Use a long unique password that doesn't match symlink or any other passwords.

Development

npm run dev     # запуск сервера напрямую через tsx, без сборки
npm test        # unit-тесты (без обращения к реальному роутеру)
npm run smoke   # live read-only проверка на реальном роутере из .env

Versions and releases

The project version (package.json, .claude-plugin/plugin.json) is bumped automatically on push to master — GitHub Actions runs semantic-release, which determines the version level based on commit messages (Angular convention):

• fix: ... → patch

• feat: ... → minor

• feat!: ... / {ANGULAR...} in commit body → major

• chore:, docs:, refactor:, test: etc. — no release is created

We never bump or edit the version manually — it's fully derived from the commit history.