Skip to main content
Glama

Zyxel USG FLEX MCP Server (zyxel-usg-mcp)

A production-ready Model Context Protocol (MCP) server written in TypeScript for Zyxel USG FLEX H Series (uOS V1.40: 50H / 100H / 200H / 500H / 700H) and USG FLEX / ATP Series (ZLD) firewalls.

Unlike mock-only CLI wrappers, zyxel-usg-mcp connects to real Zyxel hardware over Serial Console (COM3 / /dev/ttyUSB0 in ~0.5s) and SSH (hmac-sha2-256 interactive PTY), while bundling the complete 13,000+ line Zyxel uOS V1.40 CLI Reference Guide, CLI Cheatsheet, and 7 Official Zyxel SNMP MIB files for sub-5ms local V8 regex search.


Key Features

  • Real Hardware Execution (Serial + SSH):

    • Ultra-Fast Serial Console (~0.5s): Direct Win32 COM3 (kernel32 ctypes) & Linux/WSL2 /dev/ttyUSB0 (pyserial) support with automatic usbipd detection and zero PowerShell overhead.

    • Zyxel SSH Compatibility: Automatically negotiates MACs=hmac-sha2-256 and interactive PTY (zysh / uOS CLI) with automatic --More-- pagination handling.

    • Concurrency Mutex Queue: Serializes concurrent tool calls so multiple requests or shared lab users never collide on the Serial/SSH session.

  • Dual MCP Transport (Stdio & Streamable HTTP):

    • Local Stdio mode (default): Zero-dependency setup for Claude Desktop, Claude Code, Antigravity, and Cursor.

    • Shared Lab Streamable HTTP mode (--http --port 8787): Expose a connected lab USG FLEX 500H over http://<lab-host>:8787/mcp with optional Bearer token authentication (USG_MCP_TOKEN) and Read-Only guardrails (USG_READONLY=true).

  • Built-in Knowledge Base (Resources & V8 Search):

    • Full Zyxel USG FLEX H Series uOS V1.40 CLI Reference Guide (13,091 lines with Alphabetical Index).

    • Curated uOS V1.40 CLI Cheatsheet (CLI modes, PoE, UTM Signatures, Nebula Production/Gamma troubleshooting, packet flow exploration).

    • 7 Official Zyxel SNMP MIBs: ZYXEL-HW-MONITOR-MIB, ZYXEL-ZW-COMMON, ZYXEL-ZW-SMI, ZYXEL-ES-COMMON, ZYXEL-ES-SMI, ZYXEL-ES-WIRELESS, ZYXEL-ES-CAPWAP.


Related MCP server: Zyxel Switch MCP Server

MCP Tools

Tool Name

Description

usg_status

One-call status inspection for preset modules: poe, signatures, nebula, system, interfaces, cloud_helper, logs, or all_summary.

usg_cli_exec

Execute one or more read-only / diagnostic CLI commands on a Zyxel USG FLEX H (uOS) or ZLD firewall via serial or ssh.

usg_cli_config

Safely execute configuration commands inside edit running (uOS) or configure terminal (ZLD). Defaults to dry_run=true (diff preview without committing).

usg_doc_search

Sub-5ms V8 regex/keyword search across the 13,091-line uOS V1.40 CLI Reference Guide and Cheatsheet (scope: all, cheatsheet, reference, index).

usg_mib_lookup

Search the 7 bundled official Zyxel SNMP MIB files by OID name, object identifier, or keyword.

usg_usbipd

Check status, attach, or detach the FTDI USB-to-Serial Console cable (0403:6001) between Windows (COM3) and WSL2 (/dev/ttyUSB0).

MCP Resources

  • zyxel://docs/uos-cli-cheatsheet — USG FLEX H Series (uOS V1.40) Quick Cheatsheet

  • zyxel://docs/uos-cli-index — USG FLEX H Series (uOS V1.40) Alphabetical Command Index

  • zyxel://live/poe-status — Live PoE Port Status from the connected USG FLEX firewall

  • zyxel://live/signatures — Live IPS, App Patrol, IP Reputation, System Protection, Geo-IP, and Cloud Helper signature status

  • zyxel://mibs/<filename> — Official Zyxel SNMP MIB files

MCP Prompts

  • usg_health_audit — Full hardware, interface, PoE, and UTM signature health check workflow

  • usg_nebula_troubleshoot — Nebula Control Center (NCC) Callhome (TCP 4335 & d2.nebula.zyxel.com) troubleshooting workflow

  • usg_safe_config_change — Guided edit running -> diff -> commit -> copy running startup workflow


Quick Start

1. Build from Source

git clone https://github.com/JamesChan-Zy/zyxel-usg-mcp.git
cd zyxel-usg-mcp
npm run build

2. Authentication Setup

Store your firewall admin password in ~/.ssh/.usg_pass (recommended, permissions 0600) or pass USG_PASSWORD in environment variables:

echo 'YOUR_FIREWALL_PASSWORD' > ~/.ssh/.usg_pass
chmod 600 ~/.ssh/.usg_pass

3. Configure MCP Client (mcp_config.json)

Option A: Local Stdio Mode (Antigravity / Claude Desktop / Claude Code / Cursor)

{
  "mcpServers": {
    "zyxel-usg-mcp": {
      "command": "node",
      "args": ["/path/to/zyxel-usg-mcp/dist/index.js"],
      "env": {
        "USG_TRANSPORT": "serial",
        "USG_COM_PORT": "COM3",
        "USG_SERIAL_DEV": "/dev/ttyUSB0",
        "USG_HOST": "192.168.201.254",
        "USG_USER": "admin"
      }
    }
  }
}

Option B: Shared Lab Streamable HTTP Mode

Start the server on the lab host connected to the USG FLEX firewall:

USG_READONLY=false USG_MCP_TOKEN=your-secret-token node dist/index.js --http --port 8787

Connect from any team member's MCP client:

{
  "mcpServers": {
    "zyxel-usg-lab": {
      "url": "http://<lab-host-ip>:8787/mcp"
    }
  }
}

Environment Variables

Variable

Default

Description

USG_TRANSPORT

serial

Default transport (serial or ssh)

USG_COM_PORT

COM3

Windows Serial COM port

USG_SERIAL_DEV

/dev/ttyUSB0

Linux / WSL2 Serial device path

USG_BAUD

115200

Serial baud rate (115200 8N1)

USG_HOST

192.168.201.254

Default SSH IP address

USG_PORT

22

Default SSH port

USG_USER

admin

Firewall administrator username

USG_PASSWORD

(from ~/.ssh/.usg_pass)

Optional password override

USG_PASS_FILE

~/.ssh/.usg_pass

Path to file containing password on line 1

USG_READONLY

false

Set true to block all configuration changes (usg_cli_config)

USG_MCP_TOKEN

(none)

Optional Bearer token for --http mode

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage FortiGate firewalls from bootstrap to production, with safe preview/apply changes and secure credential handling. Covers inventory, VDOMs, interfaces, routing, firewall policies, VPN, security analysis, and documentation generation.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to programmatically generate Huawei eNSP .topo files that include USG6000V firewalls and S3700 switches, and then, once devices are started in eNSP, deliver configurations, run verification, and diagnose faults over Telnet. Ships with one-click health self-checks and topology-generation skills for natural-language-driven lab setup.
      31
      2
      MIT