zyxel-mcp

Ein MCP-Server, der es KI-Clients ermöglicht, Smart-Managed-Switches der Zyxel GS1900-Serie sicher auszulesen und zu konfigurieren.

Der GS1900 hat keine REST-API und kein SSH – nur eine JavaScript-lastige Web-GUI. Dieser Server macht aus dieser GUI per Reverse Engineering 26 typisierte MCP-Tools, die mit Schutzmechanismen versehen sind, damit ein LLM gefahrlos auf produktive Netzwerkhardware angesetzt werden kann.

Verifiziert gegen eine GS1900-24E mit Firmware V2.40(AAHK.1).

Warum es Schutzmechanismen braucht

Ein LLM, das einen Switch umkonfiguriert, kann sich mühelos selbst den Verwaltungszugang abschneiden – eine falsche PVID am Uplink-Port und das Gerät ist nur noch durch physisches Einstecken erreichbar. Dieser Server lehnt daher auf HTTP-Ebene jeden Vorgang ab, der die Konnektivität unterbrechen könnte.

Harte Sperren (keine Überschreibung möglich):

• Änderungen von Management-IP / DNS / Gateway / Management-VLAN

• Benutzerkonten und Authentifizierungsmethoden

• Deaktivieren der Verwaltungsdienste HTTP/HTTPS oder TELNET/SSH

• Wiederherstellung der Konfiguration, Werksreset, Firmware-Upload

• Löschen von VLAN 1 oder eines VLANs, das noch Mitgliedsports hat

• Deaktivieren eines Ports, dessen Link gerade aktiv ist

• jeder Schreibzugriff auf einen Port, der in ZYXEL_PROTECTED_PORTS aufgeführt ist (Uplinks, AP-Trunks)

Zusätzliche Sicherheitsmaßnahmen:

• Dry-run standardmäßig – jedes Schreib-Tool akzeptiert dry_run (Standard true) und liefert einen Ist-vs.-Soll-Vergleich, ohne den Switch zu verändern

• Auto-Backup – die Running-Config wird vor jedem Schreibzugriff exportiert

• Audit-Log – ein Append-only-JSONL jedes Lese- und Schreibzugriffs

• Save-on-Write – erfolgreiche Schreibzugriffe werden von running → startup persistiert

Related MCP server: zyxel-mcp-server

Installation

Erfordert 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

Registrieren Sie den Server bei einem MCP-Client über stdio, z. B. .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"
      }
    }
  }
}

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen; siehe .env.example.

Snapshots, Backups und Audit-Logs sind Betreiberdaten und nicht Teil dieses Tools. ZYXEL_SYNC_DIR hat keinen Standardwert, damit sie nie in diesem Quellbaum landen – weisen Sie ihn einem Verzeichnis außerhalb des Repositorys zu.

Tools (26)

Lesezugriffe — 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

Schreibzugriffe (Dry-run standardmäßig, Auto-Backup, Auto-Save) — set_port_vlan_membership, set_pvid, set_port_config, set_system_info, create_vlan, delete_vlan

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

Snapshot / Sync — sync_snapshot, sync_to_github

Konfigurations-Snapshots

sync_snapshot schreibt eine deterministische, wiederaufbaufähige Beschreibung des Switches in ZYXEL_SYNC_DIR; sync_to_github committet und pusht sie zusätzlich in 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

Snapshots sind idempotent: flüchtige Daten (Uptime, Systemzeit, CPU-/Speicherlast, Reihenfolge der MAC-Tabelle) werden entfernt oder sortiert, sodass ein Commit nur dann erscheint, wenn sich die Konfiguration tatsächlich geändert hat.

Vor dem Commit geschwärzt: Admin-Passwort-Hashes, SNMP-Community-Strings, RADIUS-/TACACS-Schlüssel. Seriennummer und MAC-Bereich werden für RMA-Zwecke aufbewahrt.

Das generierte README ist so gestaltet, dass jemand im Falle eines Switch-Ausfalls dasselbe Modell kaufen und das Netzwerk allein aus den committeten Dateien wiederherstellen kann.

So funktioniert es

Die Web-GUI des GS1900 wird vollständig über /cgi-bin/dispatcher.cgi gesteuert:

1. Anmeldung – das Passwort wird vom JavaScript der Anmeldeseite in eine 320 Zeichen lange Zeichenkette verschleiert (Zeichen werden umgekehrt an jedem 7. Index platziert, Längenziffern an den festen Offsets 123 und 289, Rest zufällig). Dies ist in encode_password() nachgebildet.

2. Sitzung – login_chk=1 abfragen, bis OK erscheint, dann das XSSID-Token aus der Bootstrap-Seite cmd=1 extrahieren. Es muss bei jedem Schreibzugriff sowohl als Cookie als auch als verstecktes Formularfeld gesendet werden. Pro Benutzer existiert nur eine Websitzung, daher löscht der Client veraltete Sitzungen vor der Authentifizierung.

3. Seiten – jede Funktion hat eine ganzzahlige cmd-ID, z. B. 799 Portstatus, 1283 VLAN-Liste (Ajax), 1290/1291/1292 PVID-Liste/-Bearbeitung/-Anwenden, 1293/1294 VLAN-Mitgliedschaft anzeigen/anwenden, 2049 MAC-Tabelle, 5899 Speichern von running → startup.

4. Mitgliedschafts-Schreibzugriffe müssen die aktuelle Auswahl jeder Zeile sowie die versteckten vlanMode_N-Felder zurückspiegeln, sonst werden nicht übermittelte Zeilen stillschweigend zurückgesetzt.

contrib/ enthält kleine eigenständige Skripte, die beim Reverse Engineering der GUI verwendet wurden; sie sind Referenzmaterial und nicht Teil des Servers.

Aufbau

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

Haftungsausschluss

Nicht mit Zyxel verbunden. Die Steuerung einer undokumentierten Web-GUI ist inhärent fragil – verifizieren Sie das Verhalten mit Ihrer eigenen Firmware-Version, und behalten Sie die Dry-run-Standardwerte bei, bis Sie ihr vertrauen.

Lizenz

MIT