opus-tplink-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TPLINK_HOST | No | Router address (use https://... if the router redirects). | 192.168.0.1 |
| TPLINK_ROUTERS | No | Comma-separated names of additional routers. For each name <NAME>, set TPLINK_<NAME>_HOST and TPLINK_<NAME>_PASSWORD_FILE, and optionally TPLINK_<NAME>_PROTOCOL. | |
| TPLINK_TIMEOUT | No | Per-request timeout in seconds. | 20 |
| TPLINK_PASSWORD | Yes | The plain admin password for the main router. | |
| TPLINK_BACKUP_DIR | No | Where maintenance action=backup saves config files (mode 600). | <journal>/backups |
| TPLINK_JOURNAL_DIR | No | Journal directory; also the default parent of backups and device logs. | ~/.local/state/mcp-tplink-router |
| TPLINK_DEVICE_LOG_DIR | No | Per-MAC histories written by device_log action=record. | <journal>/device-logs |
| TPLINK_PROTECTED_MACS | No | Comma-separated MACs whose VPN-client routing must not break silently. | |
| TPLINK_ALLOW_FORBIDDEN | No | Set to 1 to let router_raw_write send forbidden-tier operations. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| router_statusA | Router overview: WAN/LAN addresses, internet state, Wi-Fi bands, client counts, CPU/memory, firmware, VPN-client switch. On an extender: model, mode, uplink, mesh role. Read-only. |
| router_getA | Read one section of the router config by friendly name (e.g. dhcp, dhcp_reservations, dhcp_leases, clients, wifi, vpn_client_profiles, static_routes, access_control, upnp_mappings, firewall, time) or any form path from router_catalog. Call with no section to list sections. Secrets masked unless reveal. |
| router_catalogA | List every router form (219+), what each operation does to risk (read/normal/critical/forbidden) and whether its format is verified live or only copied from the web UI. filter narrows by text; path describes one form (fields, key, secrets). |
| router_raw_readA | Send a read-only operation to any catalogued form, e.g. path='iptv?form=setting', operation='read', or custom read ops like operation='getBlockHistory' with fields. Refuses write-type operations. |
| router_logsA | Read the router's system log (newest first when timestamps parse). Filters: level (minimum severity, e.g. WARNING), type (e.g. DHCPD, WAN), contains (text), since ('2026-11-17 08:00:00'), limit. Never changes the router's own log filter. |
| router_journalA | This server's change journal: action=list (recent changes, with ids) or action=show id=... (full before/after and requests). Use the id with router_undo. |
| router_undoA | Reverse a journaled change (writes restore old values, inserts are removed, removes re-added, updates swapped back). Refuses if the router changed since, unless force=true. Reboots/firmware/actions are not undoable. Dry run first like every write. |
| router_raw_writeA | Escape hatch: send ANY operation + fields to a catalogued form. Risk comes from the catalog (unknown ops are CRITICAL, so need a confirm_token). FORBIDDEN ops (factory reset, config restore, firmware upload, quick setup, cloud bind) also need TPLINK_ALLOW_FORBIDDEN=1. Prefer the specific tools. |
| dhcp_server_setA | DHCP server: action=get shows settings; otherwise change enable / start / end (pool) / lease_minutes (1-2880) / gateway / dns1 / dns2. Validated against the LAN subnet, the router's own IP, active leases and reservations. Disabling DHCP or a gateway other than the router is CRITICAL. |
| dhcp_reservationA | DHCP address reservations (stable IPs, e.g. for kiosk tablets). action=list (with lease status and random-MAC warnings) | leases | add (mac, ip, name) | update (mac + ip/name/enable) | remove (mac) | reserve_current (pin a client's CURRENT address; identify it by mac, current_ip or client hostname). MACs in any format. Warns when a MAC is randomised/private - that device must use its real MAC. |
| ip_mac_bindingA | IP-MAC binding (ARP binding): action=status|list (setting, bindings, live ARP table) | enable | disable | add (mac, ip, name, description) | update (mac + ip/name/description/enable; done as remove+re-add) | remove (mac) | bind_current (bind an ARP entry as-is, by mac or ip). Binding THIS machine to a different IP is CRITICAL. |
| upnpB | UPnP: action=status|list (switch + current port mappings devices opened) | enable | disable. The router offers no per-mapping delete. |
| meshA | EasyMesh: action=status|devices|clients|topology|search_status|ap_avoidance|device_detail (mac) (read) | pair (DISABLED: locked up a BE9300 in testing; use the web UI / Tether / WPS button) | enable | disable (CRITICAL if satellites are attached) | search_start | search_stop | link | unlink (CRITICAL) | reboot_satellite (CRITICAL) | add_onboarding (mac) | set_device (mac, settings={name, location, led, preferred_wifi_uplink_ap, traffic_separation, backhaul_steering}) | rebalance (clients re-pick the best unit) | bind_client (mac=unit, client_mac, bind=true|false: pin a client to a unit). Satellite firmware: maintenance action=firmware_check / satellite_firmware_update. |
| vpn_serverA | The router's VPN SERVERS (people dialling in). kind=openvpn|pptp|l2tp|wireguard; action=get | set (settings={...}) | enable | disable (CRITICAL) | accounts | accounts_add (account={...}) | accounts_update (key, account={...}) | accounts_remove (key) | connected | disconnect (key). Secrets masked unless reveal. |
| vpn_clientA | The router's VPN CLIENT (router dials out). Configure a VPN, then choose which devices use it - this is how e.g. a child's device can be sent through a filtering VPN. Profiles: action=profiles | add_profile (profile={key,...}; added disabled) | set_active_profile (key; the ENABLED profile is the one in use) | update_profile / remove_profile (key). Devices (they use WHICHEVER profile is active; there is no per-device profile): devices | candidates | add_device (mac, name?, client_type?) | set_device (mac, use_vpn=true|false) | remove_device (mac). Also status | connection_status (key) | enable | disable. Everything that changes profiles or devices is CRITICAL. |
| routingA | Static routes: action=list | system (the live routing table) | add (route={name, target, netmask, gateway, interface LAN|WAN, enable}) | update (name, route={...}) | remove (name). |
| access_controlA | Access control (who may use the network). action=status | candidates | enable | disable | set_mode (mode=black|white) | block / unblock (mac[, name]) | allow / disallow (mac). Black mode blocks listed devices; white mode blocks everything NOT listed. Switching to white mode, enabling it, or blocking THIS machine is CRITICAL. |
| parental_controlA | HomeShield parental controls (local, per profile/'owner', e.g. a child). action=owners | devices | block_history (owner_id) | today_sites (owner_id) | filter_get / allowed_sites_get (owner_id) | internet_block (owner_id, blocked=true pauses the internet, false resumes) | filter_set / allowed_sites_set (owner_id, sites=[domains]) | add_owner (owner={...}) | remove_owner (owner_id). |
| wifi_setA | Wi-Fi: action=get (band=2g|5g|6g|guest|guest_access|all) | set (band, settings={ssid|name, password, hidden, enable, channel, txpower, htmode, encryption, ...}; guest also takes guest_band=2g|5g|2g5g|6g|all; guest_access takes {access, isolate}) | smart_connect (enable). Turning a radio off is CRITICAL. This server's machine is wired, so it is not cut off. |
| wifi_scheduleB | Wi-Fi off-schedule (e.g. no Wi-Fi 23:00-07:00 on school nights). action=get | enable | disable | add (rule={start 'HH:MM', end, days [sun..sat], bands [2g,5g,6g], enable}) | update (key, rule) | remove (key). |
| port_forwardingA | Port forwarding. kind=vs (virtual servers, default) | pt (port triggering) | dmz. action=list | add (rule={name, external_port, internal_port, ip, protocol ALL|TCP|UDP, enable}) | update (name, rule) | remove (name); for dmz: list | enable (ip) | disable. Overlapping external ports are refused. |
| systemA | System settings. action=info (all of the below) | firmware_check (ask TP-Link for updates; changes nothing) | ddns (read) | device_priority (list) | set_device_priority (mac, enable, time_period) | led / led_night / eco / time / dst / hour24 / auto_upgrade / qos / firewall (no settings = read; settings={...} or enable=bool = change) | time_sync | reboot (CRITICAL, not undoable). |
| internetB | Internet (WAN). action=status (connection, IPv4/IPv6, WAN port, dual-NAT, speed, DNS privacy) | protocols | get (family=4|6, proto?) | set (family, proto=dynamic|staticip|pppoe|l2tp|pptp|dslite|v6plus|ocn for IPv4; dynamic|static|pppoe|pass|tunnel for IPv6, settings={...}) CRITICAL | renew | release (family) | ipv6_enable | ipv6_disable | autodetect | dns_privacy (settings={dns_privacy: none|doh|dot, dns_mode: default|strict, server_list: [...]}) | dns_privacy_servers (kind=doh|dot) | dns_privacy_test (settings) | mac_clone (settings={mac_clone_type, mac_custom}) | flow_control (settings={rx_enable, tx_enable}). |
| lanA | LAN side. action=status (all below + port status) | lan_ipv4 (router LAN IP/mask: CRITICAL) | lan_ipv6 | port_speed (settings={speed}) | link_aggregation (LACP: enable_agg, hashmode, lacpmode, port_settings) | flow_control (rx_enable, tx_enable) | iptv (IPTV/VLAN: enable, mode, internet/iptv/ipphone VLAN ids, IGMP, port_settings) | udp_proxy | nat (NAT and hardware NAT boost) | alg (settings={ftp, tftp, h323, rtsp, sip, pptp, l2tp, ipsec: true/false}). Firewall / ping replies: system action=firewall. No settings = read. |
| maintenanceA | Maintenance. action=info | backup (download the config to the backup folder) | backups (list) | restore (file = a backup name or path; CRITICAL, reboots) | firmware_check (router + mesh satellites, online) | firmware_update_online (CRITICAL, reboots) | firmware_status | firmware_upload (file = image path; CRITICAL) | satellite_firmware_update (mac) | ping / traceroute (target, count, size, max_hops, timeout) | operation_mode (mode=router|ap|repeater|client|multissid; none = read; CRITICAL; keep_access) | reboot_schedule (settings). Factory reset is deliberately only reachable via router_raw_write (forbidden tier). |
| adminA | Router administration. action=status | change_password (old_password_file, new_password_file; CRITICAL) | remote (remote management: enable, http_port, https_port, managers) | https | local_mode (everyone vs listed devices) | local_add / local_remove (mac, name) | recovery (password-recovery e-mail) | superadmin | permissions (what the local user may see/edit). No settings = read. |
| wifi_extraB | Wi-Fi extras. WPS pairing: action=wps_push (press the router's WPS button; the call stays connected and returns the outcome: success + the device's MAC, or timeout) | wps_client_pin (pin = the device's PIN) | wait (seconds, default 125) | wps_cancel | wps_status (a session the web page/button started) | wps_settings (enable) | wps_pin_enable / wps_pin_disable / wps_pin_generate / wps_pin_default. Also mlo (Wi-Fi 7 multi-link network) | ofdma | ofdma_mimo | twt | fast_roaming | advanced (beacon, DTIM, RTS, airtime fairness, zero-wait DFS...) | guest_bandwidth | guest_time | afc | afc_refresh | status. To add a mesh satellite use mesh action=pair. Main SSIDs/passwords/channels: wifi_set. |
| clientsB | Connected devices. action=list | rename (mac, name: the name shown everywhere) | speed (limits/speeds) | speed_limit (mac, download_kbps, upload_kbps, enable) | game_accelerator | iot_status | iot_enable | iot_disable | iot_add / iot_remove (mac or macs: move smart-home devices to the isolated IoT network). |
| usbB | USB. action=status (disks, sharing, accounts, media server, Time Machine, modem) | scan | partitions (serial) | partition (serial, uuid, enable: share/hide one partition) | eject (serial) | browse (uuid, path) | service (protocol=samba|ftp|ftpex|sftp|sftpex, enable/settings={port}) | sharing_auth | media_server | server_name | time_machine | modem (USB 4G backup internet; CRITICAL) | modem_isps. |
| device_logA | Everything the router knows about ONE device, plus a local per-MAC history. action=report (mac: online state, IP, DHCP lease/reservation, every router-log line mentioning its MAC or IP, its parental-control profile's sites today and blocked attempts, access-control / VPN / IoT status, traffic) | record (mac: append only what is NEW to /device-logs/-.jsonl; run it on a timer for a continuous log beyond what the router keeps) | history (mac, event?, limit) | list. Read-only on the router. |
| ddnsA | Dynamic DNS. action=status | refresh (provider) | tplink: add / remove / bind / unbind (domain) | noip / dyndns: login (username, domain, password_file[, wan_bind]) | logout. |
| extenderA | TP-Link range extender (RE series). action=status (model, mode, uplink signal, mesh role) | uplink (the network it connects to) | extended (networks it broadcasts) | guest | mesh | network | clients | wifi_advanced | system (mode, time, LEDs, eco, power schedule) | logs. Secrets masked unless reveal. |
| extender_setA | Change a range extender: action=led (enable) | led_night (enable, time_start, time_end) | power_schedule (enable) | reboot. (Extended networks / high-speed mode: read them with extender; writing them is not verified yet - use router_raw_write if needed.) No settings = show current values. Dry run first; critical changes need the confirm_token. Journaled and undoable (except reboot). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 33 tools
Most domain-specific tools are distinct, but router_status, router_get, router_catalog, and router_raw_read overlap heavily for read access, and broad multi-action tools like system, lan, wifi_extra, and router_raw_write can shadow specific tools. Descriptions help, but an agent still faces real selection ambiguity.
All names use snake_case, but the patterns are mixed: some are verb_noun or noun_verb forms such as router_status, dhcp_server_set, and wifi_set, while many are bare domain nouns like upnp, mesh, system, internet, lan, and clients. The set is readable but not predictable.
With 33 tools, the surface is heavy and exceeds the typical well-scoped range; several tools could likely be consolidated under broader domain actions. This is not an extreme mismatch for such a feature-rich router, but 25+ tools is too many for easy agent navigation.
Coverage is broad: WAN/LAN, Wi-Fi, DHCP, routing, VPN, mesh, parental/access control, port forwarding, USB, logs, DDNS, extender, maintenance, and raw escape hatches are all present. Minor gaps remain, such as unverified extender writes, disabled mesh pairing, and no per-mapping UPnP delete, but workarounds are documented.