Zyxel Switch MCP Server

A comprehensive Model Context Protocol (MCP) server for Zyxel switch CLI commands, enabling AI applications to interact with Zyxel switches for network configuration, monitoring, and management operations.

Status

The server opens a real interactive CLI session on the switch over SSH (default) or Telnet, and runs commands against it. Command syntax and the expected output formats come from the official Zyxel CLI Reference Guide (407 pages).

An offline mode (ZYXEL_MOCK=true) replays canned output so the server can be developed and demoed without hardware. Everything it returns is fabricated.

Features

• Live CLI sessions: SSH (ssh2) or Telnet with its own option negotiation
• Automatic privilege handling: enters enable / configure terminal on demand, including the enable-password prompt
• Pagination handling: --More-- prompts are answered automatically, so long output arrives complete
• Clean output: the echoed command and the trailing prompt are stripped before the result is returned
• Serialised commands: overlapping tool calls are queued so they cannot interleave on the shared stream
• Legacy switch support: older KEX/cipher/HMAC algorithms are offered in addition to the modern defaults
• MCP Compliance: Full Model Context Protocol implementation with tools, resources, and prompts

Supported Zyxel Models

Based on the integrated CLI documentation:

• GS1920 Series (24/48 port variants)
• GS1900 Series
• XGS1930 Series
• XGS2220 Series
• Other managed Zyxel switches with CLI access

MCP Tools (CLI Commands)

Connection Management

• zyxel_connect - Connect to a Zyxel switch
• zyxel_disconnect - Disconnect from the switch
• zyxel_connection_status - Check connection status

System Information

• zyxel_show_version - Display system version information
• zyxel_show_system_info - Show detailed system information
• zyxel_show_running_config - Display running configuration
• zyxel_show_startup_config - Display startup configuration

Interface Management

• zyxel_show_interfaces - Display interface status and configuration
• zyxel_configure_interface - Configure interface settings
• zyxel_configure_switchport - Configure switchport settings

VLAN Management

• zyxel_show_vlan - Display VLAN information
• zyxel_create_vlan - Create a new VLAN
• zyxel_delete_vlan - Delete a VLAN

Network Monitoring

• zyxel_show_mac_table - Display MAC address table
• zyxel_show_arp_table - Display ARP table
• zyxel_show_spanning_tree - Display spanning tree information
• zyxel_ping - Test network connectivity

Configuration Management

• zyxel_save_config - Save running configuration to startup
• zyxel_execute_cli - Execute raw CLI commands

MCP Resources (Read-only Data)

System Resources

• zyxel://switch/version - System version information
• zyxel://switch/system-info - Detailed system information
• zyxel://switch/running-config - Current running configuration
• zyxel://switch/startup-config - Saved startup configuration

Network Resources

• zyxel://switch/interfaces - Interface status and statistics
• zyxel://switch/vlans - VLAN configuration and status
• zyxel://switch/mac-table - MAC address table entries
• zyxel://switch/arp-table - ARP table entries
• zyxel://switch/spanning-tree - Spanning tree topology
• zyxel://switch/port-statistics - Port traffic statistics

Documentation

• zyxel://docs/cli-reference - Complete CLI command reference
• zyxel://docs/troubleshooting - Troubleshooting guide

MCP Prompts (Guided Workflows)

Setup and Configuration

• zyxel_initial_setup - Guide for initial switch setup
• zyxel_vlan_setup - Step-by-step VLAN configuration
• zyxel_port_configuration - Port configuration guide

Maintenance and Operations

• zyxel_troubleshooting - Network troubleshooting procedures
• zyxel_backup_restore - Configuration backup and restore
• zyxel_monitoring_setup - Monitoring and logging setup

Security and Performance

• zyxel_security_hardening - Security configuration best practices
• zyxel_performance_optimization - Performance tuning guide

Installation

1. Clone the repository:

git clone https://github.com/humyai99/mcp-zyxel.git
cd mcp-zyxel

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Direct Execution

npm start

As MCP Server

Configure your MCP client to use this server:

{
  "mcpServers": {
    "zyxel": {
      "command": "npx",
      "args": ["zyxel-mcp-server"]
    }
  }
}

Development Mode

npm run dev

Configuration

The server can be configured through environment variables. When host, username and password are all present, the server starts pre-configured and zyxel_connect can be called with no arguments.

• ZYXEL_DEFAULT_HOST - Default switch IP address
• ZYXEL_DEFAULT_USERNAME - Default username
• ZYXEL_DEFAULT_PASSWORD - Default password
• ZYXEL_ENABLE_PASSWORD - Password for privileged mode (falls back to the login password)
• ZYXEL_PROTOCOL - ssh (default) or telnet
• ZYXEL_PORT - Overrides the protocol default (22 for SSH, 23 for Telnet)
• ZYXEL_TIMEOUT - Command timeout in milliseconds (default: 30000)
• ZYXEL_DEBUG - Log every command and response to stderr (true/false)
• ZYXEL_MOCK - true replays canned output and never contacts a switch

Passwords are only held in memory for the lifetime of the session, and zyxel_connection_status redacts them.

Offline mode

ZYXEL_MOCK=true npm start

Examples

Connecting to a Switch

// Use the zyxel_connect tool. protocol defaults to "ssh", and port defaults
// to 22 for SSH / 23 for Telnet, so both can usually be omitted.
{
  "host": "192.168.1.100",
  "username": "admin",
  "password": "admin123",
  "enablePassword": "admin123"   // optional; only if the switch asks for one
}

Creating a VLAN

// Use the zyxel_create_vlan tool
{
  "vlanId": 100,
  "name": "Production_VLAN",
  "description": "Production network VLAN"
}

Configuring an Interface

// Use the zyxel_configure_interface tool
{
  "interface": "ethernet 1/5",
  "description": "User Workstation",
  "shutdown": false,
  "speed": "auto",
  "duplex": "auto"
}

Project Structure

src/
├── cli/
│   ├── handler.ts         # Session state, privilege modes, command queue
│   ├── transport.ts       # SSH + Telnet transports, prompt/pagination handling
│   ├── mock-transport.ts  # Offline canned output (ZYXEL_MOCK=true)
│   └── types.ts           # Type definitions
├── tools/
│   └── manager.ts         # MCP tools implementation
├── resources/
│   └── manager.ts         # MCP resources implementation
├── prompts/
│   └── manager.ts         # MCP prompts implementation
└── index.ts               # Main server entry point

test/
├── fake-switch.mjs        # Emulated Zyxel CLI over SSH and Telnet
└── transport.test.mjs     # Integration test for both transports

Development

Building

npm run build

Type Checking

npm run typecheck

Testing

The test suite starts an emulated Zyxel switch (login prompts, command echo, privilege modes, --More-- pagination) on both SSH and Telnet and drives the real transports against it, so no hardware is required.

npm test

Cleaning

npm run clean

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Supported Zyxel Models

This MCP server has been designed to work with various Zyxel switch models, including:

• GS1920 Series
• GS1900 Series
• XGS1930 Series
• XGS2220 Series
• And other Zyxel managed switches with CLI access

Support

For issues and support:

1. Check the troubleshooting guide
2. Search existing GitHub issues
3. Create a new issue with detailed information

Acknowledgments

• Model Context Protocol specification
• MCP TypeScript SDK
• Zyxel for their comprehensive CLI documentation