Skip to main content
Glama
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