Zyxel USG FLEX MCP Server
by JamesChan-Zy
README.md
# 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`.
---
## 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
```bash
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:
```bash
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)
```json
{
"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:
```bash
USG_READONLY=false USG_MCP_TOKEN=your-secret-token node dist/index.js --http --port 8787
```
Connect from any team member's MCP client:
```json
{
"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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues