zyxel-mcp

AIクライアントがZyxel GS1900シリーズのスマートマネージドスイッチを安全に読み取り・設定できるようにするMCPサーバーです。

GS1900にはREST APIやSSHがなく、JavaScript多用のWeb GUIのみが存在します。このサーバーはそのGUIをリバースエンジニアリングして26個の型付きMCPツールに変換し、LLMを本番ネットワーク機器に向けても安全になるようにガードレールで包んでいます。

GS1900-24E、ファームウェアV2.40(AAHK.1)で検証済みです。

ガードレールが必要な理由

LLMがスイッチを再設定すると、簡単に自身の管理経路を断ち切ることができます。アップリンクポートのPVIDを1つ間違えるだけで、デバイスには物理的に接続しないと到達できなくなります。そのため、このサーバーは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セッションは1つしかないため、クライアントは認証前に古いセッションをクリアします。

3. ページ — すべての機能は整数のcmd IDです。例: 799ポートステータス、1283VLANリスト（ajax）、1290/1291/1292PVIDリスト/編集/適用、1293/1294VLANメンバーシップ表示/適用、2049MACテーブル、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