Skip to main content
Glama

tplink-modem-mcp

An MCP server that lets an AI assistant run a TP-Link router or an ISP-supplied TP-Link modem on your local network, so you never have to open its web panel: see who is connected and how strong their Wi-Fi signal is, give a device a fixed IP, change the Wi-Fi, read the logs, and change anything else the web panel can. Every change is shown to you first and only applied once you approve it.

CI PyPI Python License: GPL-3.0

tplink-modem-mcp

Türkçe

It builds on tplinkrouterc6u, so every model that library supports works. On top of it, it adds a client for older ISP firmwares that library does not detect, for example the Archer C5v that Türk Telekom ships, whose web UI logs in through /cgi/login?UserName=…&Passwd=….

Ask things like:

  • "Which devices are on the Wi-Fi right now, and which one has the weakest signal?"

  • "The TV keeps dropping off. When did it leave and come back today?"

  • "Show me the router's DHCP errors from the last hour."

  • "Give the printer a fixed IP, 192.168.1.50."

  • "Turn the guest Wi-Fi off." / "Forward port 25565 to my PC."

Tools

Tool

What it does

router_status

Model, firmware, internet connection (status, external IP, uptime), LAN address, Wi-Fi networks, devices online

list_clients

Devices with hostname, IP, MAC, wired or Wi-Fi band and SSID, signal (dBm) and link rate

find_client

Search devices by name, IP or MAC

client_history

Join / leave / IP-change events recorded by this server (routers keep no such log)

wifi_networks

Every SSID with band, channel and on/off

router_logs

System log, filtered by module, text or severity

dhcp_leases, dhcp_reservations

DHCP leases and fixed addresses

ipv6_status

WAN / LAN IPv6

router_objects

Every settings object the web panel uses (Wi-Fi, DHCP, port forwarding, firewall, parental control, DNS, QoS, time, ...) and the operations it can run

router_read

Read any of those objects

set_static_ip, remove_static_ip

Give a device a fixed IP, or take it away

set_wifi

Change a Wi-Fi network's name, password, on/off, hidden

router_change

Change, add or delete anything else the web panel can (set / add / delete)

router_run

Run a router operation such as renewing DHCP or reconnecting PPPoE

reboot_router

Reboot

How changes are approved

A tool that changes the router never does it on the first call. It returns what it would do; the assistant shows that to you, and only calls again with confirm=true once you say yes. If your MCP client can ask you itself (MCP elicitation), the server also asks you directly before applying. Passwords and keys are masked in everything the server returns.

router_objects, router_read, router_change and router_run work on TP-Link's CGI firmwares: the older ISP modems and the MR / VR families. On other models the curated tools that tplinkrouterc6u supports still work.

Related MCP server: miwifi-mcp

Install

You need uv and the router's web admin password. The server has to run on a machine in the same network as the router.

Claude Code:

claude mcp add tplink-modem -e TPLINK_PASSWORD='<router password>' -- uvx tplink-modem-mcp

Claude Desktop, Cursor and other clients that take a JSON config:

{
  "mcpServers": {
    "tplink-modem": {
      "command": "uvx",
      "args": ["tplink-modem-mcp"],
      "env": { "TPLINK_PASSWORD": "<router password>" }
    }
  }
}

From a clone instead of PyPI: uv --directory /path/to/tplink-modem-mcp run tplink-modem-mcp.

Settings

Variable

Default

TPLINK_PASSWORD

(required)

web admin password

TPLINK_HOST

http://192.168.1.1

router address

TPLINK_USERNAME

admin

TPLINK_CLIENT

auto

legacy, or a tplinkrouterc6u class name such as TPLinkMRClient

TPLINK_TIMEOUT

20

seconds per request to the router

TPLINK_PRESENCE_INTERVAL

60

seconds between presence samples while the server runs; 0 turns it off

TPLINK_STATE_DIR

$XDG_STATE_HOME/tplink-modem-mcp

where the presence history is kept

TPLINK_LOG

WARNING

log level, DEBUG shows every router call

TPLINK_WRITE

on

off makes the server read-only: change tools are not offered at all

TPLINK_ALLOW

(all)

comma-separated objects or operations that may be changed, * matches a suffix, e.g. LAN_DHCP*,LAN_WLAN

TPLINK_DENY

(none)

objects or operations that may never be changed, e.g. ACT_FACTORY_RESET,USER_CFG

TPLINK_SHOW_SECRETS

0

1 shows Wi-Fi passwords and keys in reads instead of ***

Nothing is narrowed by default: the assistant can change whatever the web panel can, always with your approval. Narrow it when you want to, for example TPLINK_ALLOW=LAN_DHCP_STATIC_ADDR,LAN_WLAN for fixed IPs and Wi-Fi only.

TP-Link routers allow one admin session at a time. Calls go through a single shared session, and the legacy client keeps its login for two minutes, so the web UI may ask you to take over the session while the server is in use.

Presence history

Routers do not remember when a device came and went, so the server samples the client list once a minute and writes join, leave and IP-change events to presence.jsonl in the state folder. It only samples while it runs.

For a history around the clock, run tplink-modem-mcp sample every minute from a timer on a machine that stays on, and start the MCP server with TPLINK_PRESENCE_INTERVAL=0 so only the timer writes:

* * * * * TPLINK_PASSWORD=... uvx tplink-modem-mcp sample

Tested on

  • Archer C5v v1, firmware v1.8 (Türk Telekom), with the legacy client.

Models tplinkrouterc6u supports should work through it. If you try another model, please open a model report, whether it works or not.

Security

The password stays in an environment variable and is only sent to the router. Read tools never change anything. Change tools only preview until they are called again with confirm=true, which the server tells the assistant to do only after you approve; clients with elicitation also ask you directly. TPLINK_WRITE, TPLINK_ALLOW and TPLINK_DENY limit what can be changed at all. To report a vulnerability, see SECURITY.md.

Contributing

See CONTRIBUTING.md.

Credits

  • tplinkrouterc6u by Alex Erohin (GPL-3.0), which does most of the talking to the router; the legacy client extends its MR200 client.

  • MCP Python SDK (MIT).

  • Fonts in the brand kit: Geist (SIL OFL 1.1).

License

GPL-3.0-or-later, because the server extends tplinkrouterc6u, which is GPL-3.0.

Available Tools

17 tools
client_historyA
Read-onlyIdempotent

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.

Inputs: mac, limit, since_hours. Returns: result

dhcp_leasesB
Read-onlyIdempotent

Active DHCP leases: hostname, IP, MAC, lease time left.

Inputs: no named parameters. Returns: result

dhcp_reservationsA
Read-onlyIdempotent

Fixed IP reservations (address reservation) configured on the router.

Inputs: no named parameters. Returns: result

find_clientB
Read-onlyIdempotent

Devices whose hostname, IP or MAC contains the query (case-insensitive; '-' and ':' both work in MACs).

Inputs: query (required). Returns: result

ipv6_statusA
Read-onlyIdempotent

WAN and LAN IPv6 status, if the model supports it.

Inputs: no named parameters.

list_clientsB
Read-onlyIdempotent

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.

Inputs: include_inactive. Returns: result

reboot_routerA
Destructive

Reboot the router. The whole network and the internet drop for a minute or two. Needs confirm=true.

Inputs: confirm. Returns: result

remove_static_ipA
Destructive

Remove a device's fixed IP reservation. Without confirm=true it only shows the plan.

Inputs: mac (required), confirm.

router_changeA
Destructive

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.

Inputs: action (required), object (required), stack, confirm, +2 more.

router_logsA
Read-onlyIdempotent

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.

Inputs: limit, module, contains, max_severity. Returns: result

router_objectsA
Read-onlyIdempotent

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.

Inputs: contains.

router_readA
Read-onlyIdempotent

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.

Inputs: object (required), stack, attributes. Returns: result

router_runA
Destructive

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.

Inputs: operation (required), confirm.

router_statusA
Read-onlyIdempotent

Overview: model and firmware, internet connection (status, external IP, uptime), LAN address, Wi-Fi networks that are on, number of devices online.

Inputs: no named parameters.

set_static_ipA
Destructive

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.

Inputs: ip (required), mac (required), confirm.

set_wifiA
Destructive

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.

Inputs: network_index (required), ssid, hidden, confirm, +2 more.

wifi_networksA
Read-onlyIdempotent

Every SSID the router has, with band, channel, standard and whether it is on.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Xiaomi/Redmi routers, providing read-only queries and management capabilities such as device listing, port forwarding, DHCP reservations, and reboot control.
      MIT
    • 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants and terminal users to inspect and administer TP-Link routers through typed MCP tools, including live LTE signal and cell/band control, connected clients and DHCP reservations, Wi-Fi and LED settings, diagnostics, SMS/USSD, and guarded disruptive actions.
      39
      MIT