Skip to main content
Glama
Sign In
universal-tplink-mcp

universal-tplink-mcp

by dulithdivisekara
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Overview

TP-Link Router Builder is the canonical upstream source repository that engineers and maintains the protocol specifications, cryptographic adapters, and reverse-engineered TR-064 interfaces across the entire TP-Link router hardware ecosystem. It directly feeds and synchronizes downstream releases including tplink-cli and tplink-mcp.

Conceived in Malabe, Sri Lanka near the SLIIT Campus, this system addresses carrier routing fluctuations and tower flapping observed on Hutch 4G LTE connections using Archer MR200 gateways. To operate safely across university networks, personal hotspots, and home environments, the engine implements a zero-trust multi-environment network guard that audits default gateways and SSIDs prior to command execution.

Key capabilities include atomic single-admin session leasing (SafeSession), live 3GPP cellular telemetry extraction (RSRP, RSRQ, SNR, EARFCN, PCI), automated cell tower locking, carrier band selection, host-side TCP BBR optimization, and an upstream build pipeline covering 95 reverse-engineered router web endpoints.

Related MCP server: Omada MCP Server

Architecture & Modes

The monorepo organizes protocol handling into distinct layers, ensuring that downstream consumers (CLI power users and autonomous AI agents) interact with router hardware through authenticated, non-overlapping sessions.

Layer

Runtime / Tooling

Target Environment

Latency Profile

Session Model

Upstream Core

Python 3.10+ / Cryptography

Monorepo / CI

< 15ms internal

Stateless OID mapping

CLI Suite

Python / Ink React 19 / Go

Terminal POSIX / Windows

80-120ms execution

Atomic Lease / REPL State

MCP Server

Python stdio / Node / Docker

AI Copilots (Antigravity, Claude)

100-250ms RPC

Single-Admin SafeSession

Web Portals

Static HTML / Cloudflare Pages

Edge CDN Global

< 30ms TTFB

Schema-driven pre-rendered

graph TD
    A[Hardware Gateway 192.168.1.1] --> B[TR-064 Protocol & Cryptographic Engine]
    B --> C[Network Guard & SafeSession Leasing]
    C --> D[tplink-cli Distribution]
    C --> E[tplink-mcp Distribution]
    D --> F[CLI Web Showcase tp-link-cli-web]
    E --> G[MCP Web Showcase tp-link-mcp-web]

Project Structure

.
├── tplink_router/              # Core engine and protocol implementations
│   ├── core/                   # Session leasing, network safety, and crypto
│   ├── clients/                # Hardware-specific adapters (LTE MR vs Broadband)
│   ├── cli/                    # Command-line interface definitions and REPL
│   └── mcp/                    # Model Context Protocol 2.x server adapter
├── ink-src/                    # React 19 + Ink terminal user interface
├── docs/                       # Reverse-engineered endpoint schemas and catalog
│   ├── endpoints_catalog.json  # 95 reverse-engineered OID mappings
│   └── router_endpoints_reference.md # Complete TR-064 architectural reference
├── scripts/                    # Network optimization and cellular keepalive
├── tests/                      # Automated test suite (90 unit tests)
├── pyproject.toml              # Python package metadata and dependencies
└── README.md

Installation

Prerequisites

  • Python 3.10 or higher

  • Node.js 18 or higher (optional, required for compiling Ink React TUI)

  • Operating System: Linux, macOS, or Windows

Setup Steps

  1. Clone the repository:

    git clone https://github.com/dulithdivisekara/tplink-router-builder.git
cd tplink-router-builder

  2. Create and activate a virtual environment:

    python3 -m venv .venv
source .venv/bin/activate

  3. Install package in editable mode with development dependencies:

    pip install -e .

Usage

Router Administration via Local Runner

# Verify active network profile safety
tplink-cli profile check

# Inspect live 3GPP cellular metrics
tplink-cli signal

# Run full diagnostic suite on the default gateway
tplink-cli diag
Target Gateway : http://192.168.1.1
Hardware Model : Archer MR200 v5
Network Guard  : Verified (dulith.connect on 192.168.1.1)
LTE Status     : Connected (4G LTE FDD Band 3 / 1800 MHz)
RSRP / RSRQ    : -92 dBm / -8 dB (Signal Rating: Excellent)
Lease State    : Released atomically (SafeSession closed)

Host-Side Cellular Optimization

# Enable TCP BBR congestion control, FQ queueing, and MTU 1420 GTP clamping
sudo ./scripts/optimize-network.sh enable

# Start 28-byte background keepalive heartbeat to avoid RRC dormancy
./scripts/keepalive-pulse.sh start

Session Logging & Inspection

Every command executed through the upstream core outputs audit records to maintain session visibility without leaking plaintext credentials:

  • Audit Log Path: ~/.config/tplink-router/session.log

  • Config Storage: ~/.config/tplink-router/config.json (enforced POSIX 0600 permissions)

  • Live Inspection:

    tail -f ~/.config/tplink-router/session.log

Verification Tests

Execute the comprehensive automated test suite covering authentication handshakes, multi-environment guards, TR-064 response parsers, and band calibration algorithms:

python3 -m unittest discover tests
Ran 90 tests in 22.172s

OK

Security & Privacy

  • Single-Admin Enforcement: Routers permit only one active administrator. The SafeSession context manager acquires a lock, authenticates via RSA-1024 / AES-128, executes requests, and immediately issues an atomic logout.

  • Multi-Environment Guard: Scans default gateway MAC/IP and Wi-Fi SSID to guarantee commands never fire when connected to university, office, or public networks.

  • Destructive Operation Gates: All service-interrupting actions (reboots, band switching, cell locking) require explicit confirmation flags (confirm=True).

  • Credential Protection: Strict .gitignore rules prevent .env, credentials, session cookies, and *.log files from entering source control.

License

This project is licensed under the MIT License. Author: Dulith Divisekara.

Available Tools

39 tools
router_add_port_forwardingA

Creates a new NAT virtual server port forwarding rule on the router.

Args: name: Service or descriptive name (e.g. 'web', 'ssh', 'minecraft'). external_port: Incoming WAN port or port range (e.g. '8080' or '8000-8010'). internal_ip: LAN destination IP address (e.g. '192.168.1.150'). internal_port: LAN destination port (defaults to external_port if omitted). protocol: Transport protocol ('TCP', 'UDP', or 'ALL'). confirm: Confirmation flag to add rule. force: Set to True to bypass Network Guard safety check.

Inputs: name (required), internal_ip (required), external_port (required), force, +3 more. Returns: result

router_calibrateA

Runs autonomous RF band calibration across LTE frequencies (Band 8, 3, 1, 40, Auto) with 45s watchdog fail-safe.

Launches a real-time Live Web Dashboard on http://localhost:8765. During band switches, the router modem temporarily detaches for 5-15 seconds. The local daemon safeguards against permanent disconnection by auto-reverting if WAN drops for >45s.

Args: web: Launch real-time Web UI on localhost:8765 (default: True). port: Web dashboard port (default: 8765). dry_run: Simulate band switches without modem detachment. confirm: Confirmation flag to execute calibration.

Inputs: web, port, confirm, dry_run. Returns: result

router_check_firmwareB

Checks for available online official TP-Link firmware updates.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_clear_system_logsA

Clears the internal system event log buffer on the router.

Args: confirm: Safety confirmation. Set to True to clear logs. force: Set to True to bypass Network Guard safety check.

Inputs: force, confirm. Returns: result

router_del_port_forwardingC

Deletes an existing NAT virtual server port forwarding rule by stack ID.

Args: rule_stack: Stack identifier of the rule to remove (e.g. '2,1,1,1,0,0'). confirm: Confirmation flag to delete rule. force: Set to True to bypass Network Guard safety check.

Inputs: rule_stack (required), force, confirm. Returns: result

router_get_connected_clientsB

Retrieves all connected wired and wireless devices currently on the router LAN.

Returns hostnames, IP addresses, MAC addresses, and lease durations.

Inputs: force. Returns: result

router_get_data_limitB

Retrieves monthly cellular data allowance, billing cycle start day, and live bandwidth.

Inputs: force. Returns: result

router_get_ddnsA

Retrieves Dynamic DNS (DDNS) provider configurations (TP-Link Cloud, No-IP, DynDNS).

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_dmzB

Retrieves DMZ (Demilitarized Zone) host forwarding status and destination IP.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_guest_wifiA

Retrieves current dual-band (2.4GHz / 5GHz) Guest Wi-Fi status, SSIDs, and isolation settings.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_led_statusB

Retrieves the physical LED status and night mode schedule.

Inputs: force. Returns: result

router_get_operation_modeB

Retrieves the active router operation mode (3G/4G Router Mode vs Wireless Router Mode).

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_port_forwardingA

Lists active NAT Virtual Server port forwarding rules on the cellular WAN interface.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_reboot_scheduleA

Retrieves the automated periodic reboot schedule settings.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_rf_signalB

Retrieves real-time 4G LTE RF signal metrics (RSRP, RSRQ, SNR, EARFCN, PCI, Signal Bars).

Guides router placement and antenna alignment for maximum 4G speed in Sri Lanka (e.g. Malabe/SLIIT).

Inputs: force. Returns: result

router_get_statusA

Retrieves full device, cellular LTE, RF signal metrics, and WAN network status.

Args: force: Set to True to bypass Network Guard SSID/Gateway validation.

Inputs: force. Returns: result

router_get_system_logsA

Retrieves system and cellular event logs from the TP-Link router.

Args: lines: Maximum number of recent log entries to return (default: 50). module: Optional filter by subsystem (e.g. '4G', 'DHCP', 'System', 'DNS'). min_level: Optional minimum severity filter ('EMERG', 'ALERT', 'CRIT', 'ERROR', 'WARN', 'NOTICE', 'INFO', 'DEBUG'). force: Set to True to bypass Network Guard safety check.

Inputs: force, lines, module, min_level. Returns: result

router_get_timeB

Retrieves current router system clock, time zone, daylight savings, and NTP server status.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_upnpB

Retrieves Universal Plug and Play (UPnP) status and active dynamic port mappings.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_get_wifi_networksC

Retrieves status, SSIDs, channels, and operational state of 2.4 GHz and 5 GHz Wi-Fi radios.

Inputs: force. Returns: result

router_manage_dhcp_reservationA

Manages static DHCP IP address reservations on the router.

Args: action: 'add', 'delete', or 'list'. mac: Hardware MAC address (e.g. 'AA:BB:CC:DD:EE:FF', required for 'add' or 'delete'). ip: Desired reserved IP address (required for 'add'). confirm: Confirmation required for 'add' or 'delete'. force: Set to True to bypass Network Guard safety check.

Inputs: action (required), ip, mac, force, +1 more. Returns: result

router_profile_checkA

Inspects the current host network environment (SSID, Gateway) to ensure connection safety.

Use this tool before applying configuration changes to confirm that the host is connected to the target router and not University Wi-Fi (e.g. SLIIT) or a mobile hotspot.

Inputs: no named parameters. Returns: result

router_read_smsA

Reads incoming or sent SMS messages from the router SIM inbox (e.g. package expiry alerts).

Args: limit: Maximum number of SMS messages to retrieve (default 10). folder: Message folder ('inbox' or 'sent'). force: Set to True to bypass Network Guard safety check.

Inputs: force, limit, folder. Returns: result

router_rebootA

Initiates a graceful reboot of the TP-Link router.

IMPORTANT: Rebooting will terminate the host's internet and Wi-Fi connection for ~60-90 seconds. You MUST provide confirm=True to execute.

Args: confirm: Safety confirmation. Set to True to trigger the restart. force: Set to True to bypass Network Guard safety check.

Inputs: force, confirm. Returns: result

router_run_diagnosticC

Runs a router-side diagnostic self-test verifying physical link, WAN IP, and Internet NCSI reachability.

Inputs: force. Returns: result

router_run_ussdA

Executes a USSD query on the cellular SIM card (e.g. '*344#' for Hutch quota, '*123#' for balance).

Args: code: USSD string to send. force: Set to True to bypass Network Guard safety check.

Inputs: code (required), force. Returns: result

router_send_smsB

Sends an SMS message through the router SIM card.

Args: to_phone: Recipient phone number. message: Message text content. force: Set to True to bypass Network Guard safety check.

Inputs: message (required), to_phone (required), force. Returns: result

router_set_cell_lockA

Locks or unlocks the router to a specific cellular base station tower (EARFCN + PCI).

IMPORTANT: Changing the cell tower momentarily drops and renegotiates the cellular link. You MUST provide confirm=True to execute.

Args: enable: True to lock to cell, False to unlock (return to auto roaming). earfcn: E-UTRA Absolute Radio Frequency Channel Number (e.g. '1550' for Band 3). pci: Physical Cell Identity (e.g. '58'). confirm: Safety confirmation. Set to True to proceed with connection renegotiation. force: Set to True to bypass Network Guard safety check.

Inputs: enable (required), pci, force, earfcn, +1 more. Returns: result

router_set_data_limitA

Configures monthly cellular data quota, billing day reset, and usage alert threshold.

Args: limit_mb: Total monthly data allowance in Megabytes (e.g. 50000 for 50GB). payment_day: Day of month when billing cycle resets (1-31). warning_percent: Threshold percent to trigger alert (e.g. 90). enable: True to enforce quota, False to disable. confirm: Confirmation required to apply data quota limits. force: Set to True to bypass Network Guard safety check.

Inputs: limit_mb (required), force, enable, confirm, +2 more. Returns: result

router_set_dmzB

Enables or disables DMZ host forwarding to an internal IP address.

Args: enabled: True to enable DMZ, False to disable. ip_address: Internal IP address to receive all unmapped incoming traffic. confirm: Confirmation flag to modify DMZ. force: Set to True to bypass Network Guard safety check.

Inputs: enabled (required), force, confirm, ip_address. Returns: result

router_set_dnsA

Configures custom DNS resolvers on the router's WAN connection.

Args: primary_dns: Primary DNS IP (e.g. '8.8.8.8' for Google DNS, '1.1.1.1' for Cloudflare). secondary_dns: Secondary DNS IP (default '8.8.8.8'). force: Set to True to bypass Network Guard safety check.

Inputs: primary_dns (required), force, secondary_dns. Returns: result

router_set_guest_wifiB

Configures or toggles dual-band Guest Wi-Fi networks and local LAN isolation.

Args: band: Target band ('2.4GHz', '5GHz', or 'both'). enabled: Enable (True) or disable (False) Guest Wi-Fi on selected band. ssid: Custom SSID name for the guest network. password: WPA2-PSK password (minimum 8 characters, or empty string '' for open network). allow_lan: If True, guests can reach LAN devices; if False, guests are isolated to Internet-only. confirm: Confirmation flag to apply configuration. force: Set to True to bypass Network Guard safety check.

Inputs: band, ssid, force, confirm, +3 more. Returns: result

router_set_led_night_modeA

Configures night mode to turn off router front panel LEDs automatically during sleeping hours.

Args: enable: True to activate night mode schedule, False to disable. start_time: 'HH:MM' time when LEDs turn OFF (e.g. '22:00'). end_time: 'HH:MM' time when LEDs turn back ON (e.g. '07:00'). force: Set to True to bypass Network Guard safety check.

Inputs: enable (required), force, end_time, start_time. Returns: result

router_set_lte_bandA

Manually locks router to a specific LTE band (e.g. '3' for 1800MHz, '8' for 900MHz, '40' for 2300MHz, or 'auto').

Essential for locking to optimal Hutch/Dialog 4G towers in Sri Lanka (e.g. Malabe). IMPORTANT: Changing bands triggers cellular radio renegotiation.

Args: band: LTE Band number (e.g. '3', '8', '40') or 'auto'. confirm: Safety confirmation. Set to True to execute band change. force: Set to True to bypass Network Guard safety check.

Inputs: band (required), force, confirm. Returns: result

router_set_reboot_scheduleA

Configures or disables automated daily or weekly periodic router reboots.

Args: enabled: True to enable auto-reboot, False to disable. hours: Hour of the day in 24h format (0-23, default: 3). minutes: Minute of the hour (0-59, default: 0). mode: Repeat frequency ('daily' or 'weekly'). day_of_week: Day of week for weekly mode (1=Mon, 2=Tue, ..., 7=Sun). confirm: Confirmation flag to apply schedule. force: Set to True to bypass Network Guard safety check.

Inputs: enabled (required), mode, force, hours, +3 more. Returns: result

router_set_upnpB

Enables or disables UPnP dynamic port forwarding on the router.

Args: enabled: True to enable UPnP, False to disable. confirm: Confirmation flag to modify UPnP. force: Set to True to bypass Network Guard safety check.

Inputs: enabled (required), force, confirm. Returns: result

router_set_wifi_radioA

Enables or disables a Wi-Fi radio (2.4GHz or 5GHz) and optionally updates its SSID.

IMPORTANT: Disabling the Wi-Fi band you are currently connected to will disconnect your host! You MUST provide confirm=True to execute.

Args: band: '2.4GHz' or '5GHz'. enable: True to enable radio, False to disable. ssid: Optional new SSID name. confirm: Safety confirmation. Set to True to apply radio changes. force: Set to True to bypass Network Guard safety check.

Inputs: band (required), enable (required), ssid, force, +1 more. Returns: result

router_sync_timeA

Triggers an immediate NTP network time synchronization on the router.

Args: force: Set to True to bypass Network Guard safety check.

Inputs: force. Returns: result

router_toggle_ipv6A

Enables or disables the IPv6 stack on the router's cellular connection.

Disabling IPv6 is recommended if Hutch IPv6 routing is introducing dual-stack timeout delays.

Args: enable: True to enable IPv6, False to disable. force: Set to True to bypass Network Guard safety check.

Inputs: enable (required), force. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 39 tools

    Disambiguation4/5

    Most tools target a distinct resource+action pair (DNS, DMZ, UPnP, guest Wi-Fi, port forwarding), but the cellular-tuning cluster overlaps: router_set_cell_lock, router_set_lte_band, and router_calibrate all renegotiate the radio to different towers/bands. Similarly router_get_status, router_get_rf_signal, and router_run_diagnostic partially overlap in connectivity reporting, though descriptions do help separate them.

    Naming Consistency4/5

    Strong, predictable router_<verb>_<noun> pattern throughout (router_get_*, router_set_*, router_add_*, router_del_*), with a consistent shared arg vocabulary (confirm, force). Minor deviations: router_manage_dhcp_reservation uses a vague 'manage' verb instead of add/delete/list, router_profile_check is noun_verb order, and 'del' is abbreviated where other tools spell things out.

    Tool Count3/5

    39 tools is heavy for a single router surface and pushes well past the comfortable 3-15 range, with several near-duplicate getters that could be folded into a single status call. Each tool does map to a real router feature, so it is not gratuitous padding, but the surface is on the bloated side.

    Completeness4/5

    Coverage is broad and balanced: DHCP reservations, DNS, IPv6, Wi-Fi radios, guest networks, NAT/DMZ/UPnP, SMS/USSD, data quotas, logs, scheduling, and diagnostics are all present with get/set pairs. Gaps remain: firmware is check-only (no update action), and there is no WPS, MAC/access-control filtering, or static routing surface.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Omada MCP Server

      Zesty0wl
      A
      license
      C
      quality
      B
      maintenance
      Enables managing TP-Link Omada SDN controllers through MCP, exposing 72 tools for sites, devices, clients, networks, switch ports, firewalls, schedules, and site settings, including reboot and PoE scheduling.
      72
      1
      MIT

    • ax11000-mcp

      taroru5358
      A
      license
      B
      quality
      B
      maintenance
      Enables Claude Code and other MCP clients to inspect and manage a TP-Link router over stdio, including device lists, DHCP leases and reservations, Wi-Fi settings, firmware and IP status, mesh nodes, and safe raw endpoint requests with confirmation for writes and secret masking.
      16
      MIT

    • archer-router-mcp

      ebenezer-isaac
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM/MCP clients to read and, when explicitly allowed, modify TP-Link Archer AX53 router settings directly over the LAN using the router's own web protocol, without a browser or cloud account. It is read-first, write-gated, and lockout-aware, with tools for clients, DHCP, Wi-Fi, access control, presence history, and other router operations.
      MIT