Keenetic-router-plugin

Plugin (servidor MCP + skill) que permite al agente de IA controlar un router Keenetic mediante RCI, la misma API que usa la interfaz web del router. Funciona directamente por la red local, sin nube. El servidor MCP es autónomo y funciona con cualquier cliente MCP (por ejemplo, Codex); el skill (conocimiento de dominio sobre Keenetic para la IA) solo funciona en el ecosistema de plugins de Claude Code.

Probado en KeeneticOS 5.0.12. En otro modelo/firmware, algunas rutas RCI pueden diferir: antes de empezar a trabajar, ejecute npm run smoke (solo lectura, no cambia nada en el router).

Qué puede hacer la IA con este plugin, y qué no

Lectura: sin confirmación, en cualquier momento: versión del firmware, estado de WAN, lista de interfaces, dispositivos conectados, clientes Wi-Fi, reenvío de puertos, rutas, reservas DHCP, interfaces VPN, exportación completa de la configuración (export_config).

Cambios: solo si la IA pasó explícitamente confirm: true: cambio de contraseña Wi-Fi, habilitar/deshabilitar el punto de acceso, añadir/eliminar reenvíos de puertos, añadir/eliminar rutas, vincular/desvincular la red a un túnel VPN ya configurado, aplicar rutas en lote desde un archivo .bat. Sin confirm: true la llamada se rechaza. Se puede pedir a la IA que primero ejecute con dryRun: true — mostrará exactamente lo que se enviará al router, sin aplicar nada.

Operaciones peligrosas: requieren además ALLOW_DESTRUCTIVE=true en la configuración del servidor: reiniciar el router. Mientras la bandera no esté activada, el router no se puede reiniciar a través de la IA, ni siquiera con confirm: true.

Lo que el plugin no puede hacer en absoluto (no implementado): crear túneles VPN desde cero (WireGuard/OpenVPN/IPsec), restablecer los valores de fábrica, actualizar el firmware.

Cada llamada write/destructive (aplicada, rechazada o fallida) se escribe en audit.log.

Related MCP server: AsusWRT MCP Server

Instalación

Se necesita Node.js 20+.

1. Clone el proyecto e instale las dependencias:

   npm install
   npm run build

2. Copie .env.example a .env en la misma carpeta y complételo:

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

   En lugar de .env, los mismos valores se pueden pasar mediante --env al registrar el servidor — vélo abajo.

3. Compruebe la conexión (solo lectura, no cambia nada en el router):

   npm run smoke

   Si alguna solicitud devolvió un error — para su modelo/firmware la ruta RCI es diferente, corríjala en src/capabilities/*.ts antes de trabajar con la IA.

Conexión a Claude Code

Como plugin (recomendado — directamente con el skill):

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

Para una conexión permanente (no solo para una sesión), use /plugin install cuando coloque el proyecto en un repositorio git o en un marketplace local.

Solo el servidor, sin skill:

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

Si no creó .env, agregue las credenciales directamente aquí:

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"

Para comprobar la conexión: claude mcp list, claude mcp get keenetic o /mcp dentro de la sesión.

Después, en el diálogo se puede escribir, por ejemplo: «muestra los dispositivos conectados al router» o «cambia la contraseña del Wi-Fi de invitados».

Conexión a Codex

En ~/.codex/config.toml:

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

Seguridad

El modelo de guardia (confirm/dryRun/ALLOW_DESTRUCTIVE) protege contra acciones accidentales o descuidadas de la IA. No protege la contraseña del router en sí: si .env o la configuración llega a manos de otras personas, con esa contraseña se puede entrar al router directamente, sin pasar por el servidor ni por esas restricciones.

• export_config formalmente es de solo lectura, pero devuelve secretos en forma visible o débilmente ofuscados (hashes de contraseñas, WPA-PSK, parámetros de WireGuard): la misma información que está detrás del botón «Guardar» en la interfaz web, pero ahora en una conversación con la IA. La herramienta le pide a la IA que le advierta antes de usarla.

• Cree un usuario separado para el servicio en la interfaz web del router (Sistema → Usuarios), en lugar de usar admin cuando sea posible. Nota: algunas operaciones (en particular set_wifi_password/set_wifi_enabled) en Keenetic están disponibles solo para admin; si las necesita, use admin, pero con una contraseña nueva y única.

• No expose RCI/el administrador web a Internet — no habilite el acceso remoto, KeenDNS con acceso de administración o el reenvío de puertos hacia el administrador web para este usuario. Por defecto, Keenetic ya está cerrado desde el exterior.

• Limite el acceso a .env a nivel del sistema operativo (chmod 600 .env en macOS/Linux, propiedades del archivo → «Seguridad» en Windows). El archivo ya está en .gitignore.

• Use una contraseña larga y única, que no coincida con otras contraseñas suyas.

Desarrollo

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

Versiones y lanzamientos de interfaces

La versión del proyecto (package.json, .claude-plugin/plugin.json) se actualiza automáticamente al hacer push a master. GitHub Actions ejecuta semantic-release, que determina el nivel de la versión por los mensajes de los commits (convención Angular):

• fix: ... → patch

• feat: ... → minor

• feat!: ... / BREAKING CHANGE: ... en el cuerpo del commit → major

• chore:, docs:, refactor:, test:, etc. — no se crea release

No se cambia ni edita la versión manualmente: se deriva completamente del historial de commits.