tplink-modem-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TPLINK_LOG | No | Log level; DEBUG shows every router call. | WARNING |
| TPLINK_DENY | No | Comma-separated objects or operations that may never be changed, e.g. 'ACT_FACTORY_RESET,USER_CFG'. Defaults to none. | |
| TPLINK_HOST | No | Router address. | http://192.168.1.1 |
| TPLINK_ALLOW | No | Comma-separated objects or operations that may be changed; '*' matches a suffix, e.g. 'LAN_DHCP*,LAN_WLAN'. Defaults to all. | |
| TPLINK_WRITE | No | Set to 'off' to make the server read-only: change tools are not offered at all. | on |
| TPLINK_CLIENT | No | Client type: 'legacy', or a tplinkrouterc6u class name such as 'TPLinkMRClient'. Defaults to auto. | auto |
| TPLINK_TIMEOUT | No | Seconds per request to the router. | 20 |
| TPLINK_PASSWORD | Yes | Web admin password for the router. | |
| TPLINK_USERNAME | No | Router web admin username. | admin |
| TPLINK_STATE_DIR | No | Directory where the presence history is kept. | $XDG_STATE_HOME/tplink-modem-mcp |
| TPLINK_SHOW_SECRETS | No | Set to '1' to show Wi-Fi passwords and keys in reads instead of '***'. | 0 |
| TPLINK_PRESENCE_INTERVAL | No | Seconds between presence samples while the server runs; 0 turns it off. | 60 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Reads and manages a TP-Link router or ISP modem on the local network. Read tools are safe. Every tool that changes the router first returns a preview; show it to the user, and only call it again with confirm=true once they approve. For anything without a dedicated tool, find the setting with router_objects and router_read (the same objects the router's web UI uses) and change it with router_change. For 'device X keeps dropping' questions combine list_clients (signal), client_history and router_logs (DHCP DISCOVER lines show a device joining again).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| router_statusA | Overview: model and firmware, internet connection (status, external IP, uptime), LAN address, Wi-Fi networks that are on, number of devices online. |
| list_clientsB | Devices on the network: hostname, IP, MAC, wired or Wi-Fi band and SSID, signal (dBm, closer to 0 is better; below -75 is weak) and link rate where the router reports them. |
| find_clientB | Devices whose hostname, IP or MAC contains the query (case-insensitive; '-' and ':' both work in MACs). |
| client_historyA | Join / leave / IP-change events recorded by this server (routers keep no such log). Shows which device keeps dropping off the network and when. Sampled every TPLINK_PRESENCE_INTERVAL seconds (default 60) while the server runs. |
| wifi_networksA | Every SSID the router has, with band, channel, standard and whether it is on. |
| router_logsA | System log, newest first. module: e.g. DHCPD, PPP, DHCPC, SYSTEM. contains: text or a MAC to look for. max_severity: 0 emerg, 3 err, 4 warn, 6 info, 7 debug (everything). Note: the router clears it on reboot. |
| dhcp_leasesB | Active DHCP leases: hostname, IP, MAC, lease time left. |
| dhcp_reservationsA | Fixed IP reservations (address reservation) configured on the router. |
| ipv6_statusA | WAN and LAN IPv6 status, if the model supports it. |
| router_objectsA | Names of every settings object the router's web UI uses (LAN_WLAN, LAN_DHCP_STATIC_ADDR, WAN_IP_CONN_PORTMAPPING, FIREWALL, ...) and the operations it can run (ACT_REBOOT, ...). Filter with contains. |
| router_readA | Read a settings object: every instance, or the one at stack (e.g. "1,2"). Each row carries its _stack, which router_change needs. Passwords and keys are masked unless TPLINK_SHOW_SECRETS=1. |
| router_changeA | Change any setting the web UI can change. action: "set" (stack = the row's _stack; omit for single objects), "add" (parent_stack = the parent row's _stack, e.g. "1" for LAN_DHCP_STATIC_ADDR under LAN 1) or "delete". Read the object first so attribute names match. Without confirm=true it only shows what it would do. |
| router_runA | Run a router operation from router_objects' list, such as ACT_DHCP_RENEW or ACT_PPP_DISCONN. Without confirm=true it only shows what it would do. |
| set_static_ipA | Give a device a fixed IP (address reservation): adds it, or updates the existing reservation for that MAC. The device gets the address the next time it renews its lease. Without confirm=true it only shows the plan. |
| remove_static_ipA | Remove a device's fixed IP reservation. Without confirm=true it only shows the plan. |
| set_wifiA | Change a Wi-Fi network (index from wifi_networks): name, password, on/off, hidden. Devices on it drop and must reconnect, with the new password if it changed. Without confirm=true it only shows the plan. |
| reboot_routerA | Reboot the router. The whole network and the internet drop for a minute or two. Needs confirm=true. |
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 17 tools
Most tools target clearly distinct resources or actions (status, clients, DHCP, logs, Wi-Fi, reboot). The main overlap is that router_change can perform any setting change, including the Wi-Fi and static-IP operations handled by set_wifi, set_static_ip, and remove_static_ip; descriptions clarify that the specialized tools are convenience wrappers with plan/confirm behavior, but an agent could still hesitate between the generic and specific paths.
All names use snake_case, which is consistent, but the convention is mixed: some are verb-first (list_clients, find_client, set_wifi, reboot_router) while many are noun-only (wifi_networks, router_logs, dhcp_leases, ipv6_status, client_history) and others are noun+verb (router_read, router_change, router_run). It remains readable, but there is no single predictable verb_noun pattern.
17 tools is slightly above the typical 3–15 range and feels a bit heavy, partly because a generic settings layer (router_objects, router_read, router_change, router_run) coexists with convenience wrappers (set_wifi, set_static_ip, remove_static_ip). Still, each tool maps to a real router-management operation and the breadth of the domain justifies most of them.
The surface covers status, clients, presence history, Wi-Fi, logs, DHCP leases and reservations, IPv6, reboot, and a generic read/change/run layer for any web-UI settings object, which closes most potential gaps. Minor omissions like traffic/bandwidth monitoring or firmware updates are largely reachable through router_objects/router_read/router_change, so there are no obvious dead ends.