zyxel-mcp

An MCP server that lets AI clients safely read and configure Zyxel GS1900 series smart-managed switches.

The GS1900 has no REST API or SSH — only a JavaScript-heavy web GUI. This server reverse-engineers that GUI into 26 typed MCP tools, wrapped in guardrails that make it safe to point an LLM at production network hardware.

Verified against a GS1900-24E, firmware V2.40(AAHK.1).

Why it needs guardrails

An LLM reconfiguring a switch can trivially cut its own management path — one wrong PVID on the uplink port and the device is only reachable by physically plugging into it. This server therefore refuses, at the HTTP layer, any operation that could sever connectivity.

Hard lock-outs (no override):

• management IP / DNS / gateway / management-VLAN changes
• user accounts and authentication methods
• disabling HTTP/HTTPS or TELNET/SSH management services
• configuration restore, factory reset, firmware upload
• deleting VLAN 1, or any VLAN that still has member ports
• disabling a port whose link is currently up
• any write to a port listed in ZYXEL_PROTECTED_PORTS (uplinks, AP trunks)

Additional safety:

• Dry-run by default — every write tool takes dry_run (default true) and returns a current-vs-target diff without touching the switch
• Auto-backup — running config is exported before any write
• Audit log — append-only JSONL of every read and write
• Save-on-write — successful writes are persisted running → startup

Install

Requires 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

Register with an MCP client over stdio, e.g. .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"
      }
    }
  }
}

Configuration

All configuration is environment-based; see .env.example.

Variable	Required	Purpose
ZYXEL_HOST	yes	Switch management IP
ZYXEL_USER		Username (default admin)
ZYXEL_PASSWORD	yes	Password, or use ZYXEL_PASSWORD_FILE
ZYXEL_SCHEME		http (default) or https
ZYXEL_PROTECTED_PORTS		Ports where writes are always refused
ZYXEL_AUDIT_LOG		Audit log path
ZYXEL_BACKUP_DIR		Pre-write backup directory
ZYXEL_SYNC_DIR	for sync	Where snapshots are written
ZYXEL_SYNC_REMOTE	for sync	Git remote receiving snapshots
ZYXEL_DHCP_LEASES		DHCP lease file for MAC → hostname

Snapshots, backups and audit logs are operator data, not part of this tool. ZYXEL_SYNC_DIR has no default so they never land in this source tree — point it somewhere outside the repository.

Tools (26)

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

Writes (dry-run default, auto-backup, auto-save) — set_port_vlan_membership, set_pvid, set_port_config, set_system_info, create_vlan, delete_vlan

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

Snapshot / sync — sync_snapshot, sync_to_github

Config snapshots

sync_snapshot writes a deterministic, rebuild-ready description of the switch to ZYXEL_SYNC_DIR; sync_to_github also commits and pushes it to 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 are idempotent: volatile data (uptime, wall clock, CPU/memory load, MAC-table ordering) is stripped or sorted, so a commit appears only when the configuration genuinely changed.

Redacted before commit: admin password hashes, SNMP community strings, RADIUS/TACACS keys. Serial number and MAC range are kept for RMA purposes.

The generated README is designed so that if the switch dies, someone can buy the same model and rebuild the network from the committed files alone.

How it works

The GS1900 web GUI is driven entirely through /cgi-bin/dispatcher.cgi:

1. Login — the password is obfuscated by the login page's JavaScript into a 320-character string (characters placed in reverse at every 7th index, length digits at fixed offsets 123 and 289, remainder random). This is reimplemented in encode_password().
2. Session — poll login_chk=1 until OK, then scrape the XSSID token from the cmd=1 bootstrap page. It must be sent as both a cookie and a hidden form field on every write. Only one web session exists per user, so the client clears stale sessions before authenticating.
3. Pages — every feature is an integer cmd id, e.g. 799 port status, 1283 VLAN list (ajax), 1290/1291/1292 PVID list/edit/apply, 1293/1294 VLAN membership view/apply, 2049 MAC table, 5899 save running→startup.
4. Membership writes must echo every row's current selection plus the hidden vlanMode_N fields, or unsubmitted rows silently reset.

contrib/ holds small standalone scripts used while reverse-engineering the GUI; they are reference material, not part of the server.

Layout

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

Disclaimer

Not affiliated with Zyxel. Driving an undocumented web GUI is inherently fragile — verify behaviour against your own firmware version, and keep the dry-run defaults on until you trust it.

License

MIT