zyxel-mcp

Un servidor MCP que permite a los clientes de IA leer y configurar de forma segura los switches con gestión inteligente de la serie Zyxel GS1900.

La serie GS1900 no tiene API REST ni SSH; solo una interfaz web cargada de JavaScript. Este servidor aplica ingeniería inversa a esa interfaz y la convierte en 26 herramientas MCP tipadas, protegidas con salvaguardas que hacen seguro apuntar un LLM a hardware de red en producción.

Verificado contra un GS1900-24E, firmware V2.40(AAHK.1).

Por qué necesita salvaguardas

Un LLM que reconfigura un switch puede cortar trivialmente su propio camino de gestión: basta un PVID incorrecto en el puerto de enlace ascendente (uplink) para que el dispositivo solo sea accesible conectándose físicamente. Por eso, este servidor rechaza en la capa HTTP cualquier operación que pueda romper la conectividad.

Bloqueos estrictos (sin anulación):

• cambios de IP de gestión / DNS / pasarela / VLAN de gestión

• cuentas de usuario y métodos de autenticación

• deshabilitar los servicios de gestión HTTP/HTTPS o TELNET/SSH

• restauración de la configuración, reinicio de fábrica, carga de firmware

• eliminar la VLAN 1, o cualquier VLAN que todavía tenga puertos miembro

• deshabilitar un puerto cuyo enlace esté actualmente activo

• cualquier escritura en un puerto incluido en ZYXEL_PROTECTED_PORTS (uplinks, troncales de AP)

Medidas de seguridad adicionales:

• Simulación por defecto (dry-run) — toda herramienta de escritura acepta dry_run (por defecto true) y devuelve una diferencia (diff) entre la configuración actual y la objetivo sin tocar el switch

• Copia de seguridad automática — la configuración en ejecución se exporta antes de cualquier escritura

• Registro de auditoría — JSONL de solo añadidura (append-only) con cada lectura y cada escritura

• Guardar al escribir — las escrituras correctas se persisten de configuración en ejecución → configuración de inicio

Related MCP server: zyxel-mcp-server

Imágenes

Requiere Python 3.10+.

git clone git@github.com:hugil/zyxel-mcp.git
cd zyxel-mcp
cp .env.example .env      # then edit .env
uv run mcp-zyxel

Regístralo con un cliente MCP sobre stdio, por ejemplo, .vscode/mcp.json:

{
  "servers": {
    "zyxel": {
      "command": "uv",
      "args": ["--directory", "/path/to/zyxel-mcp", "run", "mcp-zyxel"],
      "env": {
        "ZYXEL_HOST": "192.168.1.1",
        "ZYXEL_USER": "admin",
        "ZYXEL_PASSWORD": "...",
        "ZYXEL_PROTECTED_PORTS": "1,4"
      }
    }
  }
}

Configuración

Toda la configuración se basa en variables de entorno; ver .env.example.

Las instantáneas, las copias de seguridad y los registros de auditoría son datos del operador, no de esta ferraa. ZYXEL_SYNC_DIR no tiene una valor por defecto para que nunca terminen en el árbol del source — apunta fuera del repositorio.

Herramientas (12)

Lecturas — get_system_info, get_port_status, get_port_counters, list_vlans, get_vlan_membership, get_mac_table, get_pvids, get_stp_config, get_lag_config, get_loopguard_config, get_lldp_config, get_port_security_config, get_syslog_config, get_mirror_config, get_running_config_text

Escrituras (simulación por defecto, copia de seguridad automática, guardado automático) — set_port_vlan_membership, set_pvid, set_port_config, set_system_info, create_vlan, delete_vlan

Mantenimiento — backup_config, save_running_to_startup, reboot(ack='REBOOT')

Instantánea / sincronización — sync_snapshot, sync_to_github

Instantáneas de configuración

sync_snapshot escribe una descripción determinista y lista para reconstruir el switch en ZYXEL_SYNC_DIR; por su parte, sync_to_github además hace commit y envía (push) a ZYXEL_SYNC_REMOTE.

$ZYXEL_SYNC_DIR/
  README.md              generated topology: VLAN table, port map,
                         membership matrix, MAC/device inventory
  running-config.cfg     full CLI config, secrets redacted
  annotations.json       hand-edited MAC -> hostname/role/notes,
                         never overwritten by a snapshot
  system.json  vlans.json  ports.json  membership.json
  mac-table.json  inventory.json  lldp-neighbors.json
  running-config.raw.cfg unscrubbed, git-ignored — never committed

Las instantáneas son idempotentes: los datos volátiles (uptime, reloj del sistema, carga de CPU/memoria, orden de la tabla MAC) se eliminan o se ordenan, de modo que solo aparece un commit cuando la configuración ha cambiado realmente.

Antes de publicar se eliminan: los hashes de las contraseñas de administrador, las cadenas de comunidad SNMP y las claves RADIUS / TACACS. El número de serie y el rango MAC se conservan para fines de RMA.

El README generado está diseñado para que, si el switch se estropeha, alguien pueda comprar el mismo modelo y reconstruir la red usando únicamente los archivos incluidos en el commit.

Cómo funciona

La interfaz web de la GS1900 se maneja por completo mediante /cgi-bin/dispatcher.cgi:

1. Inicio de sesión — la contraseña está ofuscada por el JavaScript de la página de login en una cadena de 320 caracteres (los caracteres se colocan en orden inverso en cada índice múltiplo de 7, los dígitos en las posiciones fijas 123 y 289, y el resto al azar). Este comportamiento se reimplementa en encode_password().

2. Sesión — Sondea login_chk=1 hasta obtener OK y después extrae el token XSSID de la página de inicio cmd=1. Debe enviarse tanto como cookie como campo de formulario oculto en cada escritura. Solo existe una sesión web por usuario, así que el cliente elimina las sesiones caducadas antes de autenticarse.

3. Páginas — cada función es un id entero cmd, por ejemplo: 799 estado del puerto, 1283 lista de VLAN (ajax), 1290/1291/1292 lista/edición/aplicación de PVID, 1293/1294 vista/aplicación de pertenencia a VLAN, 2049 tabla MAC, 5899 guarda ejecución → inicio.

4. Escrituras de pertenencia a VLAN — deben reflejar la selección actual de todas las filas más los campos ocultos vlanMode_N; de lo contrario, las filas no enviadas se restablecen en silencio.

contrib/ contiene pequeños scripts independientes usados en la ingeniería inversa de la interfaz; son material de referencia, no forman parte del servidor.

Estructura

src/mcp_zyxel/
  server.py        MCP tool + resource definitions
  zyxel_client.py  auth, session, XSSID handling, locked-cmd enforcement
  zyxel_ops.py     typed reads/writes per feature page
  safety.py        connectivity lock-outs, protected ports, audit, backups
  sync.py          snapshot, scrubbing, topology README, git push
contrib/           standalone probing scripts (reference)
probe.py           dump dispatcher pages and their form fields

Descargo de responsabilidad

No está afiliado con Zyxel. Manejar una interfaz web no documentada es inherentemente frágil: comprueba el comportamiento con tu propia versión de firmware y mantén el modo de simulación por defecto hasta que tengas confianza en él.

Licencia

MIT