Tenda HG7 Router Controller MCP Server

Overview

The SLT Fiber Tenda HG7 Controller provides programmatic automation and autonomous agent integration for the Tenda HG7 Dual-Band AC1200 GPON ONT router deployed across Sri Lanka Telecom (SLT-MOBITEL) fiber optic broadband lines. Built on a Realtek RTL960x SoC running the embedded Boa 0.95.15 web server accessible at http://192.168.1.1, the router normally requires manual web dashboard interactions, lacks an official REST API, and locks out concurrent administrator sessions.

This project delivers:

• Autonomous Agent Control via MCP: A standards-compliant Model Context Protocol server exposing 12 structured tools for optical telemetry, device inventories, diagnostic ping, Wi-Fi mutations, WAN profiles, VoIP SIP status, and TR-069 configuration to AI assistants (Google Antigravity, Claude, Cursor).

• Engineering CLI (tenda-ctl): Global command-line interface with formatted terminal tables for network administrators and engineers.

• Dual-Role Architecture: Transparent support for both standard end-user (admin) and ISP Super Administrator (administrator) privilege levels with dynamic role detection.

• Protocol Emulation Engine: Reverse-engineered implementation of Realtek's 32-bit checksum algorithm (postTableEncrypt), automatic session lifecycle teardown, and base64 passphrase encryption.

• Strict ISP Safety Protections: Hardcoded write-protection guardrails that prevent accidental modification of SLT WAN VLANs (VLAN 20 Internet PPPoE, VLAN 10 Voice IPoE, VLAN 30 PeoTV) or optical registration states.

Related MCP server: sfrbox-mcp

Architecture & Role Privileges

The embedded web server dynamically binds client sessions to distinct JavaScript menus based on the authenticated credentials.

sequenceDiagram
    autonumber
    actor User as Engineer / AI Agent
    participant CLI as tenda-ctl / MCP Server
    participant Core as TendaClient Engine
    participant Router as Tenda HG7 (192.168.1.1)

    User->>CLI: Execute Command / Tool Call
    CLI->>Core: Authenticate (admin / administrator)
    Core->>Router: POST /boaform/admin/formLogin (Checksum + Referer)
    Router-->>Core: HTTP 301/302 Redirect (Session Active)
    Core->>Router: GET/POST Target Endpoint (e.g. status_pon.asp)
    Router-->>Core: Raw HTML / XML Response
    Core->>Router: POST /boaform/admin/formLogout (Release 5-min Lock)
    Core->>CLI: Parsed Pydantic Model
    CLI->>User: Formatted Rich Table / JSON-RPC Response

Project Structure

.
├── assets/
│   ├── screenshots/               # Sanitized terminal outputs (help, status, pon)
│   └── tenda-logo.png             # Optimized official transparent logo
├── docs/
│   ├── api-reference.md           # Python client methods and schemas
│   ├── endpoints-map.md           # Complete 44-page router endpoint mapping
│   └── super-admin-guide.md       # Technical guide to Super Admin subsystems
├── tenda_controller/
│   ├── __init__.py                # Package exports and version metadata
│   ├── client.py                  # HTTP client, checksum, and session engine
│   ├── cli.py                     # Rich command-line interface (tenda-ctl)
│   ├── exceptions.py              # Domain error types and safety guardrails
│   ├── mcp_server.py              # FastMCP server for AI agent tool calling
│   └── models.py                  # Pydantic schemas for router telemetry
├── tests/
│   ├── __init__.py
│   ├── test_checksum.py           # Verification of Realtek checksum vectors
│   ├── test_client_mock.py        # Mock unit tests for basic client parsers
│   └── test_super_admin_mock.py   # Mock unit tests for Super Admin parsers
├── .env.example                   # Environment configuration template
├── CODE_OF_CONDUCT.md             # Contributor Covenant Code of Conduct v2.1
├── CONTRIBUTING.md                # Development, testing, and PR guidelines
├── install.sh                     # Turnkey system installer script
├── LICENSE                        # MIT License
├── pyproject.toml                 # Build configuration (setuptools)
├── README.md                      # Project documentation
├── requirements.txt               # Pinned runtime dependencies
└── SECURITY.md                    # Security advisories and disclosure policy

Installation

Method 1: Turnkey One-Line Installer (Recommended)

Clone the repository and run the automated installer script:

git clone https://github.com/dulithdivisekara/slt-fiber-tenda-controller.git
cd slt-fiber-tenda-controller
chmod +x install.sh
./install.sh

The installer automatically:

• Checks Python 3.10+ and pip availability.

• Handles PEP 668 environments (--break-system-packages).

• Deploys tenda-ctl into ~/.local/bin.

• Cleans up legacy binary artifacts.

• Ensures ~/.local/bin is exported in your shell profile (~/.bashrc, ~/.zshrc, ~/.profile).

Method 2: Standard Pip Install

# Inside a virtual environment:
pip install -e .

# Or user-mode install on modern Linux:
pip install --break-system-packages --user -e .

Method 3: Environment Configuration

Copy the sample environment template and set credentials for automated tools:

cp .env.example .env

TENDA_HOST=192.168.1.1
TENDA_USERNAME=admin
TENDA_PASSWORD=admin
TENDA_SUPER_USERNAME=administrator
TENDA_SUPER_PASSWORD=your_super_admin_password_here

Tool Catalog & Usage

The tenda-ctl utility provides 7 core subscriber commands and 4 ISP Super Admin inspection commands:

System Telemetry & Hardware Status

tenda-ctl status

Optical Fiber Power (PON) Diagnostics

Check your fiber link health directly from your terminal:

tenda-ctl pon

Optical Compliance Standards: SLT Class B+ GPON requires Rx optical power between -8.0 dBm and -28.0 dBm with ONU State O5 (Operational / Synchronized).

Connected Client Inventory

tenda-ctl devices

Wireless Network Inspection & Mutation

Inspect current wireless configurations:

tenda-ctl wifi show

Safely update wireless network credentials without risking internet disconnects:

# Update 5GHz SSID and Passphrase
tenda-ctl wifi set --band 5g --ssid "SLT-Fiber-5G" --password "YourStrongPassword123"

# Update 2.4GHz SSID
tenda-ctl wifi set --band 2.4g --ssid "SLT-Fiber-2.4G"

Configuration Backup & Export

tenda-ctl backup backup_config.xml

Upstream Network Ping

tenda-ctl ping 1.1.1.1

Super Admin Inspection

Authenticate with ISP Super Administrator credentials via --super or the TENDA_SUPER_PASSWORD environment variable to inspect low-level fiber infrastructure subsystems:

# Broadband multi-WAN interface profiles (VLAN 20 Internet, VLAN 10 Voice, VLAN 30 PeoTV)
tenda-ctl wan --super

# Landline VoIP SIP telephony registrar and media configuration
tenda-ctl voip --super

# Remote management Access Control Lists (ACL rules on LAN and WAN)
tenda-ctl acl --super

# TR-069 Auto-Configuration Server (ACS) CWMP telemetry
tenda-ctl tr069 --super

Model Context Protocol Server

The controller exposes 12 structured tools for autonomous AI agents via FastMCP.

Quick Setup for AI Agents (One-Shot Prompt)

If you use an AI coding assistant (such as Google Antigravity, Claude Code, Cursor, Windsurf, or Cline), paste the following prompt directly into your AI chat to install and configure this MCP server automatically on your machine:

Agent Installation Prompt:

Please install and configure the Tenda HG7 Router Controller MCP server on this machine:

1. Check if https://github.com/dulithdivisekara/slt-fiber-tenda-controller.git is already cloned; if not, clone it and enter the directory:
   git clone https://github.com/dulithdivisekara/slt-fiber-tenda-controller.git
   cd slt-fiber-tenda-controller

2. Install the package in editable mode with dependencies:
   pip install -e .

3. Register the MCP server named "tenda-hg7" in my agent/environment MCP configuration file (e.g., mcp.json, claude_desktop_config.json, or agent-specific MCP settings):
   - Command: python3 (or absolute path to current python virtual environment)
   - Args: ["-m", "tenda_controller.mcp_server"]
   - Environment variables:
     - TENDA_HOST: "192.168.1.1" (or router gateway IP)
     - TENDA_USERNAME: "admin"
     - TENDA_PASSWORD: "admin"
     - (Optional for advanced ISP diagnostics) TENDA_SUPER_USERNAME: "administrator", TENDA_SUPER_PASSWORD: "<your-super-admin-password>"

4. Verify connectivity by invoking the tool `tenda_get_status` or running `tenda-ctl status`.
5. Confirm when the MCP server is registered and print the router status, optical Rx power, and firmware version.

Manual Configuration (Claude Desktop / Antigravity / Cursor)

Add the server entry to your MCP configuration file (mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "tenda-hg7": {
      "command": "python3",
      "args": ["-m", "tenda_controller.mcp_server"],
      "env": {
        "TENDA_HOST": "192.168.1.1",
        "TENDA_USERNAME": "admin",
        "TENDA_PASSWORD": "admin",
        "TENDA_SUPER_USERNAME": "administrator",
        "TENDA_SUPER_PASSWORD": "<SUPER_ADMIN_PASSWORD>"
      }
    }
  }
}

Complete Tool Inventory

• tenda_get_status(): Hardware status, software version, CPU, memory, and uptime.

• tenda_get_optical_power(): Rx/Tx optical power (dBm), laser temperature, voltage, and ONU state.

• tenda_get_connected_devices(): Real-time list of all LAN and WLAN connected client devices.

• tenda_get_wifi_config(band): Inspect active SSID, channel, and encryption for "2.4g" or "5g".

• tenda_set_wifi_config(band, ssid, password): Safely update Wi-Fi credentials with base64 encryption.

• tenda_backup_config(destination_path): Export clean XML configuration file.

• tenda_ping(target): Perform diagnostic ICMP ping from router to upstream host.

• tenda_reboot(): Dispatch a graceful soft restart to the router.

• tenda_get_wan_profiles(): Inspect SLT multi-WAN interfaces (VLAN 20, 10, 30).

• tenda_get_voip_config(): Inspect SLT landline SIP proxy, domain, and media ports.

• tenda_get_acl_rules(): Inspect management service Access Control List exposure.

• tenda_get_tr069_config(): Inspect TR-069 Auto-Configuration Server parameters.

Controlling the Router via AI Agents (Antigravity & Claude)

FastMCP exposes the router controller over standard I/O (stdin/stdout) via JSON-RPC. Once registered, AI agents automatically discover the 12 tools and their parameter schemas.

Sample Agent Prompts

You can issue natural language commands directly to your AI assistant:

• Optical Laser Diagnostics:

  "Check my fiber optical power levels and confirm if the Rx dBm is within SLT's compliant range." → Dispatches tenda_get_optical_power()

• Wi-Fi SSID & Password Management:

  "Update my 5GHz Wi-Fi SSID to 'Divisekara-5G' and set the password to 'SecurePass2026'." → Dispatches tenda_set_wifi_config(band="5g", ssid="Divisekara-5G", password="SecurePass2026")

• Connected Device Inventory:

  "List all devices currently connected to my Wi-Fi and Ethernet ports." → Dispatches tenda_get_connected_devices()

• Configuration Disaster Recovery:

  "Export a full router configuration backup to local storage." → Dispatches tenda_backup_config(destination_path="backup_config.xml")

• Upstream Latency Test:

  "Ping 1.1.1.1 from the router to verify upstream connectivity." → Dispatches tenda_ping(target="1.1.1.1")

Session Logging & Inspection

The client automatically manages session creation and teardown to prevent the router's 5-minute admin session lockout (AUTO_LOGOUT_TIME=300).

• Sessions authenticate with custom Realtek checksum headers.

• Each context-managed command immediately logs out upon exit via /boaform/admin/formLogout.

• To inspect raw HTTP debug logs:

  python3 -c "import logging; logging.basicConfig(level=logging.DEBUG); from tenda_controller import TendaClient; c = TendaClient(); c.login(); print(c.get_status()); c.logout()"

Verification Tests

Run the automated test suite verifying checksum calculation, parser robustness, and Super Admin mock fixtures:

python3 -m unittest discover -s tests -v

Expected output:

test_backup_checksum (test_checksum.TestChecksum.test_backup_checksum) ... ok
test_login_checksum (test_checksum.TestChecksum.test_login_checksum) ... ok
test_rtk_urlencode (test_checksum.TestChecksum.test_rtk_urlencode) ... ok
test_band_resolution (test_client_mock.TestClientMock.test_band_resolution) ... ok
test_connected_devices_null_ip_handling (test_client_mock.TestClientMock.test_connected_devices_null_ip_handling) ... ok
test_get_pon_status_parsing (test_client_mock.TestClientMock.test_get_pon_status_parsing) ... ok
test_get_status_parsing (test_client_mock.TestClientMock.test_get_status_parsing) ... ok
test_wifi_password_validation (test_client_mock.TestClientMock.test_wifi_password_validation) ... ok
test_get_acl_rules (test_super_admin_mock.TestSuperAdminMock.test_get_acl_rules) ... ok
test_get_tr069_config (test_super_admin_mock.TestSuperAdminMock.test_get_tr069_config) ... ok
test_get_voip_config (test_super_admin_mock.TestSuperAdminMock.test_get_voip_config) ... ok
test_get_wan_profiles (test_super_admin_mock.TestSuperAdminMock.test_get_wan_profiles) ... ok
test_mcp_super_admin_unconfigured_password_error (test_super_admin_mock.TestSuperAdminMock.test_mcp_super_admin_unconfigured_password_error) ... ok
test_permission_denied_for_normal_admin (test_super_admin_mock.TestSuperAdminMock.test_permission_denied_for_normal_admin) ... ok

Ran 14 tests in 0.012s
OK

Security & ISP Safety Boundaries

Protection of Critical ISP Subsystems

The router is deployed on an active SLT Fiber connection carrying multi-VLAN traffic:

• VLAN 20 (ppp0_nas0_0): Broadband Internet and TR-069 remote telemetry.

• VLAN 10 (nas0_1): SLT Voice / VoIP IPoE interface.

• VLAN 30 (nas0_2): PeoTV IPTV multicast bridged interface.

The tenda-controller engine hardcodes strict write protections:

• Under no circumstances will the tool submit requests targeting ATM_VC_TBL (WAN profiles) or GPON_PLOAM.

• The configuration backup routine specifically validates that the reset action keyword is absent, eliminating accidental factory reset risks.

• For complete security details, see SECURITY.md.

Ethical Boundaries & Credential Protection Policy

• This project is strictly designed for subscribers managing and automating their own locally owned/rented CPE devices.

• In adherence with responsible security practices, this project will never provide, support, or integrate tools or scripts designed to harvest, scan, or discover credentials belonging to other subscribers or third-party networks.

Contributing & Governance

• See CONTRIBUTING.md for local development, testing, and PR submission guidelines.

• All contributors are expected to uphold the standards outlined in our Code of Conduct.

• Detailed technical breakdowns of Super Admin subsystems can be found in the Super Admin Guide.

License

This project is licensed under the MIT License.

Search Indexing & SLT Fiber Keywords

This repository is optimized for Sri Lankan fiber broadband subscribers, network administrators, and home automation developers:

• Hardware & Firmware: Tenda HG7 Dual-Band AC1200 GPON ONT, Realtek RTL960x SoC, Boa Web Server 0.95.15, firmware v1.0.17.

• ISP Network Profiles: SLT-MOBITEL Fiber (Sri Lanka Telecom FTTH), VLAN 20 Internet PPPoE, VLAN 10 Voice SIP VoIP (ftth.sltims.lk), VLAN 30 PeoTV IPTV multicast.

• Diagnostics & Telemetry: SLT optical power check (tenda-ctl pon), Class B+ laser attenuation limits (-8 dBm to -28 dBm), GPON ONU state O5.

• AI Automation: Model Context Protocol (MCP), FastMCP server, Google Antigravity router control, Claude Desktop networking tools.