Keenetic-router-plugin

Ein Plugin (MCP-Server + Skill), das einem KI-Agenten die Verwaltung eines Keenetic-Routers über RCI ermöglicht — dieselbe API, die auch die Weboberfläche des Routers nutzt. Es arbeitet direkt im lokalen Netzwerk, ohne Cloud. Der MCP-Server ist eigenständig und funktioniert mit jedem MCP-Client (z. B. Codex), der Skill (Domänenwissen über Keenetic für die KI) — nur in der Plugin-Umgebung von Claude Code.

Getestet mit KeeneticOS 5.0.12. Bei einem anderen Modell/anderer Firmware können einzelne RCI-Pfade abweichen — führen Sie vor Beginn der Arbeit npm run smoke aus (read-only, ändert nichts am Router).

Was die KI mithilfe dieses Plugins kann — und was nicht

Lesen — ohne Bestätigung, jederzeit: Firmware-Version, WAN-Status, Liste der Schnittstellen, verbundene Geräte, Wi-Fi-Clients, Port-Weiterleitungen, Routen, DHCP-Reservierungen, VPN-Interfaces, vollständiger Export der Konfiguration (export_config).

Änderungen — nur wenn die KI explizit confirm: true übergibt: Ändern des Wi-Fi-Passworts, Aktivieren/Deaktivieren des Zugangspunkts, Hinzufügen/Entfernen von Port-Weiterleitungen, Hinzufügen/Entfernen von Routen, Anbinden/Lösen eines Netzwerks an einem bereits konfigurierten VPN-Tunnel, paketweises Anwenden von Routen aus einer .bat-Datei. Ohne confirm: true wird der Aufruf abgelehnt. Man kann die KI bitten, den Aufruf zunächst mit dryRun: true auszuführen — sie zeigt dann, was genau auf den Router gesendet würde, ohne dabei etwas zu Erwachsen – ohne dass etwas angewendet wird.

Gefährliche Operationen — erfordern zusätzlich ALLOW_DESTRUCTIVE=true in der Serverkonfiguration: Neustart des Routers. Solange das Flag nicht gesetzt ist, kann der Router auch mit confirm: true nicht per KI neu gestartet werden.

Was das Plugin grundsätzlich nicht kann (nicht implementiert): VPN-Tunnel von Grund auf neu anlegen (WireGuard/OpenVPN/IPsec), Zurücksetzen auf die Werkseinstellungen, Firmware aktualisieren.

Jeder write-/destructive-Aufruf (angewendet, abgelehnt oder mit Fehler fehlgeschlagen) wird in audit.log geschrieben.

Related MCP server: AsusWRT MCP Server

Installation

Voraussetzung: Node.js 20+.

1. Klonen Sie das Projekt und installieren Sie die Abhängigkeiten:

   npm install
   npm run build

2. Kopieren Sie .env.example in .env in diesem Ordner und füllen Sie es aus:

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

   Statt der .env lassen sich dieselben Werte auch über --env bei der Registrierung des Servers übergeben — siehe unten.

3. Prüfen Sie die Verbindung (read-only, ändert nichts am Router):

   npm run smoke

   Falls eine Anfrage einen Fehler zurückgibt, weicht der RCI-Pfad für Ihr Modell/Ihre Firmware ab — korrigieren Sie ihn in src/capabilities/*.ts, bevor Sie mit der KI arbeiten.

Verbindung zu Claude Code

Als Plugin (empfohlen — direkt mit Skill):

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

Für eine dauerhafte Verbindung (bzw. nicht nur für eine Session) verwenden Sie /plugin install, sobald das Projekt in einem Git-Repository oder lokalen Marketplace liegt.

Nur Server, ohne Skill:

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

Wenn Sie keine .env angelegt haben, fügen Sie die Anmeldedaten direkt hier ein:

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"

Verbindung prüfen: claude mcp list, claude mcp get keenetic oder /mcp innerhalb einer Session.

Danach können Sie im Dialog zum Beispiel schreiben: „Wann zeigst du die mit dem Router verbundenen Geräte“ oder „Ändere das Passwort des Gäste-Wi-Fi“.

Verbindung zu Codex

In ~/.codex/config.toml:

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

Sicherheit

Das Guard-Modell (confirm/dryRun/ALLOW_DESTRUCTIVE) schützt vor zufälligen oder arbeitsunfällig Aktionen der KI. Es schützt nicht das Router-Passwort selbst — wenn .env oder die Konfiguration in falsche Hände gerät, könnte man sich mit diesem Passwort direkt am Router anmelden, unter Umgehung des Routers und aller dieser Beschränkungen.

• export_config ist formal read-only, gibt aber Geheimnisse in offener bzw. schwach obfuskierter Form zurück (Passwort-Hashes, WPA-PSK, WireGuard-Parameter) — dieselben Informationen, die in der Weboberfläche hinter der Schaltfläche „Speichern“ stehen, nur eben jetzt im Chat mit der KI. Das Tool weist die KI an, Sie vor dem Aufruf darauf hinzuweisen.

• Legen Sie einen separaten Benutzer für den Dienst der Website im Router an (System → Benutzer) und verwenden Sie nicht admin, wenn möglich. Hinweis: Einige Funktionen, insbesondere set_wifi_password/set_wifi_enabled, funktionieren auf diesen Keenetic nur mit admin — wenn benötigt, verwenden Sie admin, aber mit einem neuen, eindeutigen Passwort.

• Öffnen Sie RCI/Web-Admin nicht für das Internet — aktivieren Sie keinen Remote-Zugriff, kein KeenDNS mit Zugriff auf Verwaltung keine Port-Weiterleitung auf die Web-Admin-Oberfläche des Dienstes für dieses Konto. Standardmäßig ist Keenetic von außen ohnehin geschlossen.

• Beschränken Sie den Zugriff auf .env auf der Anwendungsserver (OS)(chmod 600 .env macOS/Linux oder Dateieigenschaften → „Sicherheit“ on Windows). Die Datei ist bereits in .gitignore eingetragen.

• Verwenden Sie ein langes, eindeutiges Passwort, das nicht mit Ihren anderen Passwörtern übereinstimmt.

Entwicklung

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

Versionen und Releases

Die Projektversion (package.json, .claude-plugin/plugin.json) wird bei jedem Push auf master automatisch erhöht — GNUHUB Actions startet semantic-release, das die Versionsnummer anhand der Commit-Text (Angular-Konvention) bestimmt:

• fix: ... → Patch

• feat: ... → Minor

• feat!: ... / BREAKING CHANGE: ... im Commit-Body → Major

• chore:, docs:, refactor:, test: usw. sagen wir — kein Release

Die Version erhöhen oder bearbeiten wir nicht von Hand — sie leitet sich vollständig aus der Commit-Historie ab.