zte-f680-mcp

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

Control your router port forwarding rules conversationally, without opening the web UI.

Features

Quick-open flow (v0.2.0+)

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.

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 DHCP leases from my router

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.
• 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 .
cp .env.example .env   # fill in your credentials
python -m zte_f680_mcp.server

License

MIT © Alberto Diaz