keenetic-mcp
Controla un router Keenetic en lenguaje natural: qué dispositivos están en la red y qué están usando, el estado del Wi-Fi y de las interfaces, por qué internet está caído, las políticas de enrutamiento y los segmentos aislados de invitados o IoT. Se ejecuta en tu máquina y se comunica con el router a través de la LAN mediante su propia API RCI, sin instalar nada en el router. Cada cambio se lee de nuevo y se verifica antes de informar que se ha completado, porque el router acepta algunos comandos incorrectos en silencio. Nada se guarda hasta que lo pidas, y primero se realiza una copia de seguridad.
Documentación
keenetic-mcp
Controla tu router Keenetic desde Claude, Codex, Cursor o cualquier agente MCP.
Pregunta a tu agente sobre tu red en lenguaje natural. Sin memoria USB, sin Entware, nada instalado en el router.
> 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.
Por qué
- Nada en el router. Habla con la API HTTP propia del router a través de tu LAN. Sin unidad USB, sin Entware, sin modificación de firmware.
- Funciona en cualquier Keenetic. El conjunto de herramientas se adapta a lo que tu modelo y firmware específicos realmente soportan.
- Seguro por construcción. Los cambios nunca se guardan a menos que lo pidas, se hace una copia de seguridad antes del primero, y cada cambio se lee de nuevo y se verifica antes de informar que está hecho.
- Solo lectura si lo deseas. Una bandera y el agente físicamente no puede cambiar nada.
Instalación
Claude Code
/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keenetic
Luego ejecuta el asistente de configuración en tu terminal:
npx -y keenetic-mcp init
Codex
codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp init
Esto trae las habilidades junto con el servidor. Para el servidor por sí solo:
codex mcp add keenetic -- npx -y keenetic-mcp
Cualquier otra cosa
{
"mcpServers": {
"keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
}
}
El asistente encuentra tu router desde la puerta de enlace predeterminada, confirma que realmente es un Keenetic, comprueba la contraseña contra él y guarda la contraseña en el llavero de tu sistema operativo. Solo la dirección y el inicio de sesión van en un archivo de configuración.
¿Prefieres variables de entorno? KEENETIC_HOST, KEENETIC_USER y KEENETIC_PASSWORD anulan todo, que es lo que quieres en un contenedor.
Lo que puede hacer
Leer
| Herramienta | |
|---|---|
list_devices | todos los dispositivos, filtrados por activos, cableados, inalámbricos o bloqueados, ordenados por tráfico o señal |
get_device | un dispositivo completo: concesión, velocidad Wi-Fi, política, horario, tráfico |
list_interfaces | enlaces WAN, puentes, puntos de acceso, túneles VPN |
get_interface | una interfaz completa, incluidos los pares WireGuard |
get_wifi_status | radios por banda, con recuentos de clientes |
get_internet_status | accesibilidad, y qué comprobación falló |
list_routes | tabla de enrutamiento, o solo la ruta predeterminada |
list_policies | políticas de conexión para enrutamiento selectivo |
get_system_info | modelo, firmware, CPU, memoria, componentes instalados |
get_config_state | cambios no guardados, quién cambió qué y cuándo |
list_segments | todos los puentes, y si la interfaz web lo lista como segmento |
backup_config | descargar la configuración a un archivo local |
Cambiar
| Herramienta | |
|---|---|
update_device | renombrar, bloquear o permitir, asignar una política de enrutamiento, horario o prioridad |
set_interface_state | levantar o bajar una interfaz |
create_segment | una red de invitados o IoT que la interfaz web realmente lista, con Wi-Fi, DHCP y enrutamiento VPN opcional |
delete_segment | eliminar un segmento y todo lo creado con él |
save_config | hacer que los cambios pendientes sobrevivan a un reinicio |
Vía de escape
| Herramienta | |
|---|---|
rci_call | cualquier ruta de API del router, para lo que las herramientas anteriores no cubran |
Habilidades incluidas
El plugin incluye cuatro habilidades, para que el agente sepa cómo se comporta tu router en lugar de adivinar. Un directorio de plugin sirve tanto para Claude Code como para Codex: leen manifiestos diferentes pero comparten las mismas habilidades y la misma definición de servidor.
- keenetic-rci enseña el árbol de API del router: qué rutas existen, cuáles devuelven 100 KB y cómo recuperar la sintaxis exacta de un comando desde la propia configuración del router.
- keenetic-safe-changes enseña el flujo de trabajo de cambios: qué protege y qué no protege el sistema a prueba de fallos del router, y qué interfaces cortarán tu propio acceso.
- keenetic-segments cubre la construcción de una red aislada que el router admitirá que existe. La forma obvia produce una red de invitados que transporta tráfico perfectamente y nunca aparece en la interfaz web, porque un segmento está respaldado por VLAN y la VLAN es la parte que todos omiten.
- keenetic-troubleshoot es un manual de diagnóstico ordenado para "internet está caído", "el Wi-Fi es malo" y "un dispositivo no puede conectarse".
Seguridad
- Nada se guarda a menos que lo pidas. Los cambios se aplican a la configuración en ejecución y se descartan al reiniciar hasta que se llame a
save_config. El servidor nunca lo llama por su cuenta. - Se hace una copia de seguridad automáticamente antes del primer cambio de una sesión.
- Cada cambio se verifica. El router acepta algunos comandos incorrectos en silencio y no cambia nada, por lo que cada escritura se lee de nuevo y se compara antes de informar que fue exitosa.
- El modo de solo lectura es realmente de solo lectura. Con
--read-only, las herramientas de escritura no se registran en absoluto en lugar de registrarse y rechazar, por lo que el agente nunca las ve. - Tu contraseña va al llavero del sistema, no en un archivo de configuración, y nunca en un registro o una respuesta de herramienta.
- Solo LAN. Sin nube, sin telemetría, sin conexión saliente a nada más que a tu router.
Dónde se almacena la contraseña en cada plataforma y cómo informar algo de forma privada están en SECURITY.md.
Routers compatibles
RCI, la API que esto utiliza, es una parte estándar de KeeneticOS en lugar de una característica de modelos caros, por lo que funciona en toda la gama. Verificado contra un Keenetic Ultra (KN-1811) con KeeneticOS 5.1.3.
Modelos en la rama 5.1 actual: Giga (KN-1010), Hero (KN-1011, KN-1012), Start y Starter (KN-1111, KN-1112, KN-1121), Air y Explorer (KN-1613, KN-1621), Extra y Carrier (KN-1713, KN-1714, KN-1721), Ultra y Titan (KN-1810, KN-1811, KN-1812). El hardware más antiguo en 4.x y anteriores también tiene RCI; el conjunto de herramientas se adapta a los componentes que cada router realmente tiene.
Cómo funciona
Los routers Keenetic exponen RCI, un espejo JSON de su árbol de línea de comandos, a través de HTTP. Este servidor se autentica con el esquema de desafío-respuesta del router, mantiene una sesión viva a través de las preguntas del agente y da forma a las respuestas para que quepan en el contexto de un modelo: solo la lista de interfaces en bruto es de 32 KB, y la tabla NAT supera los 100 KB.
No hay documentación pública coherente para RCI, por lo que docs/rci-api.md son las notas tomadas mientras se construía esto: el protocolo de autenticación, las rutas que existen, las trampas y cómo recuperar la sintaxis de un comando desde el propio router.
Desarrollo
npm install
npm test # no router required
npm run typecheck
npm run build
Una copia de trabajo informa su versión como 0.0.0-dev, porque no hay ninguna versión escrita en ninguna parte de las fuentes. Pon KEENETIC_MCP_VERSION en un .env en la raíz del repositorio para decir lo contrario; el mismo archivo puede contener KEENETIC_HOST y KEENETIC_PASSWORD para que no tengas que exportarlos. Una variable de entorno real siempre gana sobre ese archivo, y una copia instalada nunca lee uno.
Las pruebas se ejecutan contra fixtures sanitizados capturados de un router real. Para actualizarlos y ejecutar una prueba de humo de solo lectura contra el tuyo:
KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smoke
Los fixtures se anonimizan de forma determinista y una prueba escanea todo el repositorio en busca de cualquier cosa que parezca una dirección MAC real, IP privada o clave.
El asistente de configuración lee una contraseña desde la terminal, a la que ninguna prueba unitaria puede acceder: la entrada canalizada toma una ruta de código completamente diferente. Esa parte se verifica con un script que maneja un pty real, por lo que necesita una terminal y no puede ejecutarse en CI:
KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.exp
Publicación
Un lanzamiento es una etiqueta y nada más. No hay commit de versión que escribir, porque no hay versión en el repositorio que cambiar: package.json lleva 0.0.0-dev, los manifiestos de plugin no llevan ninguna, y el flujo de trabajo de lanzamiento estampa la etiqueta en package.json inmediatamente antes de publicar sin hacer commit.
git tag v0.2.2 && git push origin v0.2.2
El flujo de trabajo rechaza una etiqueta que no nombre una versión, y una prueba rechaza un árbol que tenga una versión escrita, por lo que los dos nunca pueden discrepar. Los plugins fijan keenetic-mcp@^0, que solo sigue la versión principal y está pensado para editarse una vez, en 1.0.
Licencia
MIT