zyxel-mcp

一个 MCP 服务器，让 AI 客户端能够安全地读取和配置 Zyxel GS1900 系列智能管理型交换机。

GS1900 没有 REST API 或 SSH——只有依赖 JavaScript 的 Web GUI。该服务器将该 GUI 逆向工程为 26 个类型化的 MCP 工具，并包裹在护栏中，使其可以安全地让 LLM 操作生产网络硬件。

已针对 GS1900-24E 固件 V2.40(AAHK.1) 验证。

为什么需要护栏

LLM 重新配置交换机时，很容易切断自身的管理路径——只要在上行端口上设置一个错误的 PVID，设备就只能通过物理插拔才能访问。因此，该服务器在 HTTP 层拒绝任何可能切断连接的操作。

硬性锁定（不可覆盖）：

• 管理 IP / DNS / 网关 / 管理 VLAN 更改

• 用户账户和认证方法

• 禁用 HTTP/HTTPS 或 TELNET/SSH 管理服务

• 配置恢复、恢复出厂设置、固件上传

• 删除 VLAN 1，或任何仍有成员端口的 VLAN

• 禁用当前链路已启用的端口

• 任何对 ZYXEL_PROTECTED_PORTS 中列出的端口（上行链路、AP 中继）的写入

额外安全措施：

• 默认干运行——每个写入工具都带有 dry_run（默认 true），并返回当前与目标的差异，而不触碰交换机

• 自动备份——任何写入前都会导出运行配置

• 审计日志——每次读取和写入的追加式 JSONL 记录

• 写入即保存——成功的写入会从运行配置持久化到启动配置

Related MCP server: zyxel-mcp-server

安装

需要 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

通过 stdio 注册到 MCP 客户端，例如 .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"
      }
    }
  }
}

配置

所有配置均基于环境变量；参见 .env.example。

快照、备份和审计日志是操作员数据，不属于本工具的一部分。ZYXEL_SYNC_DIR 没有默认值，因此它们永远不会落入此源代码树中——请将其指向仓库之外的某个位置。

工具（26 个）

读取 — 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

写入（默认干运行、自动备份、自动保存）— set_port_vlan_membership、set_pvid、set_port_config、set_system_info、create_vlan、delete_vlan

维护 — backup_config、save_running_to_startup、reboot(ack='REBOOT')

快照 / 同步 — sync_snapshot、sync_to_github

配置快照

sync_snapshot 将交换机的确定性、可重建描述写入 ZYXEL_SYNC_DIR；sync_to_github 还会将其提交并推送到 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

快照是幂等的：易变数据（运行时间、墙钟时间、CPU/内存负载、MAC 表排序）会被剥离或排序，因此只有在配置真正更改时才会出现提交。

提交前已编辑：管理员密码哈希、SNMP 团体字符串、RADIUS/TACACS 密钥。序列号和 MAC 范围保留用于 RMA 目的。

生成的 README 设计为：如果交换机损坏，有人可以购买相同型号，并仅凭提交的文件重建网络。

工作原理

GS1900 Web GUI 完全通过 /cgi-bin/dispatcher.cgi 驱动：

1. 登录 — 密码被登录页面的 JavaScript 混淆为 320 字符的字符串（字符每隔 7 个索引反向放置，长度数字位于固定偏移 123 和 289，其余随机）。这在 encode_password() 中重新实现。

2. 会话 — 轮询 login_chk=1 直到 OK，然后从 cmd=1 引导页面抓取 XSSID 令牌。每次写入都必须将其作为 cookie 和隐藏表单字段发送。每个用户只有一个 Web 会话，因此客户端在认证前会清除过期的会话。

3. 页面 — 每个功能都是一个整数 cmd ID，例如 799 端口状态、1283 VLAN 列表（ajax）、1290/1291/1292 PVID 列表/编辑/应用、1293/1294 VLAN 成员视图/应用、2049 MAC 表、5899 保存运行→启动。

4. 成员写入必须回显每一行的当前选择以及隐藏的 vlanMode_N 字段，否则未提交的行会静默重置。

contrib/ 包含逆向工程 GUI 时使用的小型独立脚本；它们是参考材料，不属于服务器的一部分。

布局

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

免责声明

与 Zyxel 无关联。驱动未记录的 Web GUI 本质上是不稳定的——请针对自己的固件版本验证行为，并在信任之前保持干运行默认值开启。

许可证

MIT