zte-f680-mcp

MCP Server (Model Context Protocol) to manage and inspect a ZTE ZXHN F680 GPON router from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Agents SDK, Cline, Continue, etc.).

Control NAT / port forwarding and read WiFi, DHCP, DMZ, WAN and device status from your router conversationally, without opening the web UI.

Features

NAT / port forwarding

Read-only status (v0.3.0+)

Generic

Quick-open flow

Ask your assistant plainly and it will confirm before touching the router:

You: open port 8080 Assistant: Your local IP is 192.168.1.128. Should I forward 8080 → 192.168.1.128:8080? You: yes Assistant: ✓ Rule added.

Under the hood the assistant calls zte_get_local_ip (to pick the correct interface even on multi-homed hosts) and then zte_open_port(port=8080). If you want a different internal port or IP, just say so and the assistant switches to zte_add_port_forward with your values.

What's new in v0.3.0

v0.3.0 adds six read-only tools that translate the router's cryptic internal fields into human-friendly tables. For example:

WiFi 2.4 GHz
  SSID:        HomeNetwork          Canal:     1 (manual)
  Estado:      ON                   Estandar:  g,n     Ancho: 20MHz
  Seguridad:   WPA/WPA2 AES         Clave:     YourRealPassword
  BSSID:       24:d3:f2:c6:97:b6    Oculta:    NO
  TxPower:     100%                 Max clientes: 16
  Trafico:     TX 1.29 GB / RX 97.9 MB       Asociaciones: 1

Under the hood, the codebase was split into focused modules (http_client, parsers, pages, formatters, server) and a new parser handles the router's third HTML layout (plain <td class="tdright"> tables used for WAN status). The project now ships with 32 unit tests running against real HTML fixtures captured from the router — no hardware needed to develop.

Requirements

• Python 3.10+

• A ZTE ZXHN F680 router reachable on the local network

• The admin credentials of the router's web panel

Install & configure

The easiest way is with uv (or pipx). No cloning, no venv.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zte": {
      "command": "uvx",
      "args": ["zte-f680-mcp@latest"],
      "env": {
        "ZTE_HOST": "192.168.1.1",
        "ZTE_USER": "1234",
        "ZTE_PASSWORD": "your_password_here"
      }
    }
  }
}

Tip: @latest makes uvx check PyPI on every launch and use the newest version, so users get updates automatically. Remove @latest (just "zte-f680-mcp") to pin to whatever was installed first.

Claude Code (CLI)

claude mcp add zte \
  --env ZTE_HOST=192.168.1.1 \
  --env ZTE_USER=1234 \
  --env ZTE_PASSWORD=your_password_here \
  -- uvx zte-f680-mcp@latest

Cursor / Windsurf / Cline / Continue

Add the same block as Claude Desktop in the corresponding MCP settings file of each client.

OpenAI Agents SDK (Python)

from agents.mcp import MCPServerStdio

zte = MCPServerStdio(
    params={
        "command": "uvx",
        "args": ["zte-f680-mcp@latest"],
        "env": {
            "ZTE_HOST": "192.168.1.1",
            "ZTE_USER": "1234",
            "ZTE_PASSWORD": "your_password_here",
        },
    }
)

Upgrading existing installs

If you registered the server before and want to jump to the newest release:

# Option 1: force-refresh the cache
uvx --refresh zte-f680-mcp

# Option 2: wipe the cache for this package only
uv cache clean zte-f680-mcp

After this, the next time your MCP client launches the server, uvx will fetch the latest version.

Alternative: classic pip install

pip install --upgrade zte-f680-mcp

Then point your MCP client at the installed script:

{
  "mcpServers": {
    "zte": {
      "command": "zte-f680-mcp",
      "env": {
        "ZTE_HOST": "192.168.1.1",
        "ZTE_USER": "1234",
        "ZTE_PASSWORD": "your_password_here"
      }
    }
  }
}

Configuration

The server reads three environment variables (or a local .env file):

Example prompts

Once the MCP is registered you can ask your assistant things like:

List the NAT rules on my ZTE router
Open TCP port 8080 forwarded to 192.168.1.100
Delete port forwarding rule number 2

Show the WiFi status (both bands)
Which devices are connected to the router?
What's my public IP and how long has the WAN been up?
Show me the WiFi clients with their signal strength
Is the DMZ enabled?
What firmware version is running?

How it works

• Auth: SHA256(password + random) with dynamic tokens (Frm_Logintoken, Frm_Loginchecktoken) extracted from the login page.

• Session: Expires ~60 s idle. The server re-authenticates automatically every 45 s.

• Anti-CSRF: Each write operation requires a fresh _SESSION_TOKEN fetched from the page.

• HTML parsing: Three formats coexist on the router — Transfer_meaning('field','value') JS calls (most config pages), <td id="Frm_*"> tables with HTML entity values (device info), and plain <td class="tdright"> tables (WAN status). Each has its own dedicated parser.

• Protocol codes: 0 = TCP+UDP, 1 = UDP, 2 = TCP.

• Transport: MCP over stdio.

Stack

• FastMCP (mcp[cli])

• httpx (async HTTP client)

• python-dotenv

• pydantic

Development

git clone https://github.com/Picaresco/MCP-ZTE-F680.git
cd MCP-ZTE-F680
python -m venv venv && . venv/Scripts/activate   # Windows
# source venv/bin/activate                         # Linux / macOS
pip install -e ".[test]"
cp .env.example .env   # fill in your credentials
python -m zte_f680_mcp.server

Run the test suite (no router required — tests use captured HTML fixtures):

pytest tests/ -v

To regenerate fixtures from your own router (if firmware differs):

python scripts/capture_fixtures.py

License

MIT © Alberto Diaz