zyxel-mcp

AI 클라이언트가 Zyxel GS1900 시리즈 스마트 매니지드 스위치를 안전하게 읽고 구성할 수 있게 해주는 MCP 서버입니다.

GS1900에는 REST API나 SSH가 없고 JavaScript 기반 웹 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 웹 GUI는 전적으로 /cgi-bin/dispatcher.cgi를 통해 구동됩니다.

1. 로그인 — 비밀번호는 로그인 페이지의 JavaScript에 의해 320자 문자열로 난독화됩니다(문자가 7번째 인덱스마다 역순으로 배치되고, 길이 숫자는 고정 오프셋 123과 289에, 나머지는 무작위). 이는 encode_password()에서 재구현됩니다.

2. 세션 — login_chk=1을 OK가 될 때까지 폴링한 다음 cmd=1 부트스트랩 페이지에서 XSSID 토큰을 스크랩합니다. 모든 쓰기에서 쿠키와 숨겨진 양식 필드로 모두 전송해야 합니다. 사용자당 웹 세션이 하나만 있으므로 클라이언트는 인증 전에 오래된 세션을 정리합니다.

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과 관련이 없습니다. 문서화되지 않은 웹 GUI를 구동하는 것은 본질적으로 취약합니다. 자체 펌웨어 버전에서 동작을 확인하고, 신뢰할 때까지 드라이런 기본값을 유지하세요.

라이선스

MIT