opus-tplink-mcp
Full management of TP-Link Archer (Wi-Fi 7 / BE series) routers through the router's own web-UI forms: reads router status, logs, clients and any of 238 catalogued forms, and performs safety-gated writes for WAN/IPv6, DNS-over-HTTPS/TLS, LAN and link aggregation, IPTV/VLAN, DHCP reservations and IP-MAC binding, Wi-Fi (including WPS, MLO, OFDMA, guest networks, schedules), EasyMesh, VPN server/client profiles, static routing, access and parental controls, port forwarding, UPnP/DMZ, USB sharing, DDNS, firmware and config backup/restore, diagnostics (ping/traceroute), QoS and administration. Every change is dry-run first with risk tiers and confirm tokens, verified by re-reading the router, journaled with before/after state, and undoable.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
opus-tplink-mcp
A complete, safety-first MCP server for TP-Link Archer routers (Wi-Fi 7 / BE series). 31 tools covering virtually everything the router's web UI can do. Every change goes through the same pipeline: dry run → review → apply → verify → journal → undo.
Designed and re-engineered by Claude Opus 5.5 (Anthropic), with Fable 5.2 advising, for vehoelite. Grown from consigcody94/mcp-tplink-router (MIT).
Not affiliated with, endorsed by, or supported by TP-Link or Anthropic. "TP-Link" and "Archer" are trademarks of TP-Link. Use at your own risk: this software changes live network equipment.
Why this one
Everything, not just the basics. All 238 forms the web UI uses are catalogued and reachable. Every major feature also has a dedicated tool: WAN and IPv6, DoH/DoT, LAN, IPTV/VLAN, link aggregation, DHCP, IP-MAC binding, VPN server and client, routing, access control, parental controls, Wi-Fi (incl. WPS, MLO, OFDMA, guest), port forwarding, UPnP, DMZ, ALG, firewall, EasyMesh, USB sharing, DDNS, backup/restore, firmware, diagnostics and administration.
Safe by construction. Every write is a dry run first. Critical changes need a one-time confirm token. Everything is journaled with before/after state and can be undone. Writes are verified by re-reading the router, and a change the router silently ignores is reported as
no_effect, not "success".Field-tested. 84 write operations were exercised live across an Archer BE9300 (firmware 1.2.4) and an Archer BE4800 (older, encrypted firmware): change, verify, undo, verify restored. More than a dozen firmware quirks found that way are handled for you (see Firmware quirks).
router_catalogmarks every operationlive,ui(from the web UI's code) ornone.Multi-router. Manage several routers from one server, including older firmware that uses the encrypted LuCI protocol (e.g. Archer BE4800 1.0.x).
Related MCP server: ax11000-mcp
Tools (31)
Area | Tool | Highlights |
Overview |
| WAN/LAN, internet state, Wi-Fi, clients, CPU/memory, firmware |
| Read any section or any of the 238 forms; per-operation risk tier and verification status | |
| System log with level/type/text/time filters (never touches the router's own log filter) | |
| Everything about one MAC: lease, reservation, every log line mentioning it, parental-control sites and blocked attempts, access/VPN/IoT status, traffic. Plus a local per-device history beyond what the router keeps | |
Safety |
| Every change with before/after; undo with conflict detection |
| Escape hatch, gated by the catalog's risk tiers | |
Internet |
| Connection type (DHCP, static, PPPoE, L2TP, PPTP, DS-Lite, v6plus, OCN), IPv6 (all modes), lease renew/release, DNS-over-HTTPS / DNS-over-TLS, MAC clone, WAN flow control, live speed / dual-NAT |
LAN |
| LAN IPv4/IPv6, port speed, link aggregation (LACP), flow control, IPTV / VLAN, UDP proxy, NAT / hardware NAT boost, ALG |
DHCP |
| Pool, lease, DNS; reservations with random-MAC detection |
| ARP binding, bind current devices, conflict checks | |
Wi-Fi |
| Per-band and guest SSIDs, passwords, channels, power, guest access/isolation, smart connect |
| WPS push button and PIN (returns the outcome and the paired MAC), Wi-Fi 7 MLO network, OFDMA/MU-MIMO, TWT, advanced radio settings, guest bandwidth/time limits, AFC | |
| Wi-Fi off periods | |
Mesh |
| EasyMesh status, devices, topology, naming/placing units, client steering, satellite reboot/unlink |
VPN |
| OpenVPN / PPTP / L2TP / WireGuard servers and accounts; VPN-client profiles and per-device routing |
Routing |
| Static routes and the live routing table |
Security |
| Allow/block lists; HomeShield profiles, sites, pause internet |
Ports |
| Virtual servers, port triggering, DMZ; UPnP and its mappings |
Clients |
| Rename devices, per-device speed limits, IoT network isolation, game accelerator |
USB |
| Drives and partitions (scan, browse, share/hide a partition, eject), Samba/FTP/SFTP sharing, media server, Time Machine, USB 4G modem |
DDNS |
| TP-Link DDNS, No-IP, DynDNS |
Maintenance |
| Config backup and restore, firmware (online, image upload, mesh satellites), ping / traceroute, operation mode, reboot schedule |
Admin |
| Admin password (RSA-encrypted like the web UI), remote management, HTTPS, local-management list, recovery e-mail, user permissions |
System |
| SPI firewall / ping replies, LEDs, eco mode, time/NTP/DST, auto-update, QoS, device priority, reboot |
Read tools are annotated readOnlyHint; write tools are annotated destructiveHint.
How it talks to the router
Login:
tplinkrouterc6u.TplinkRouterV1_11(...).authorize()(RSA login), or the encryptedTplinkRouterfor older firmware.Requests: our own
application/x-www-form-urlencodedPOST to/cgi-bin/luci/;stok=<stok>/admin/<module>?form=<form>, the same requests the web UI sends. The URL carries only?form=;operationand every field go in the body. Multipart is used for backup, restore and firmware images.One session per tool call: the router allows one admin login, so each call logs in and always logs out. If the web UI or the Tether app is logged in, log it out. (WPS pairing is the one exception: it stays logged in until pairing ends, because logging out cancels WPS.)
Retries: a failed login, or an ambiguous error while reading or planning, is retried once. A write is never resent. If a write times out or the connection drops, the server logs in again, re-reads, and reports whether the change was applied.
Safety model
Tier | Examples | To apply |
read | every read, ping/traceroute, config backup | nothing |
normal | add a reservation, block a phone, change an SSID, WPS push |
|
critical | LAN IP, any WAN form, DHCP off, radio off, region, white-list access control, blocking this machine, VPN-client changes, admin / remote management, firmware, restore, reboot, operation mode, firewall off |
|
forbidden | factory reset, quick setup, cloud bind/unbind, debug shell |
|
Dry run by default. Without
apply=truea write tool returns the plan, a field-level diff, warnings, the risk tier and (for critical changes) aconfirm_token. It sends nothing.Confirm tokens are an HMAC over the exact requests, which embed the values being replaced. A token is valid for 5 minutes and is refused if the router changed since the dry run. Uploads are bound to the file's SHA-256.
Forms are read-merge-written, sending the field allowlist from the web UI's own code for that form, or only the changed fields where the UI does that.
Table rows are changed one at a time: re-load the table, find the row by its key, check it is unchanged, then send the request with the fresh index.
Collateral check: after every remove or update, the whole table is compared before and after. If any other row vanished or changed, the result is
status: "collateral", the remaining steps are not sent, androuter_undocan re-add the lost rows.Verification: after a write the router is re-read, and the result is
applied, amismatch, orno_effect(accepted but ignored).Validation: DHCP pools, reservations, bindings and routes are checked against the subnet, the router's own IP, leases and conflicts. A randomised/private MAC gets a warning.
Journal:
~/.local/state/mcp-tplink-router/journal.jsonl(directory 0700, file 0600). The full before state is fsynced before the first request; the exact fields sent (wire) and the result follow. The journal keeps secrets so undo can restore them.Undo:
router_undo id=...restores old values, removes inserts, re-adds removed rows and swaps updates back. It refuses if the router changed since, unless you passforce. Reboots, firmware and other one-way actions are not undoable.Secrets (PSKs, passwords, private/preshared keys, PINs, tokens) are masked in every result, diff and error unless you pass
reveal=true. Account passwords are read from files, never from tool arguments.
Configuration
python -m venv venv && venv/bin/pip install -e ".[dev]"
cp .env.example .env # or pass the variables from your MCP client configVariable | Default | Meaning |
|
| Router address ( |
| The plain admin password | |
|
| Per-request timeout (s) |
|
| Journal (also the default parent of backups and device logs) |
|
| Where |
|
| Per-MAC histories written by |
| Comma-separated MACs whose VPN-client routing must not break silently (e.g. a filtered child's laptop). Changes affecting them are called out by name. | |
| unset |
|
MCP client entry (stdio):
{"command": "/path/to/venv/bin/mcp-tplink-router", "env": {"TPLINK_HOST": "192.168.0.1", "TPLINK_PASSWORD": "..."}}Several routers
TPLINK_HOST/TPLINK_PASSWORD is router main. To add more:
TPLINK_ROUTERS=upstairs
TPLINK_UPSTAIRS_HOST=https://192.168.1.1
TPLINK_UPSTAIRS_PASSWORD_FILE=/path/to/router2.pw
TPLINK_UPSTAIRS_PROTOCOL=encrypted # older firmware (e.g. BE4800 1.0.x): encrypted LuCIEvery tool takes
router(defaultmain).router_statuslists the configured routers.Journal entries record the router, and
router_undoalways targets the router the change was made on.Risk tiers are per router. VPN-client protection applies to
main; on other routers, access-control mode/enable and parental internet pause are critical. Removing the last allowlisted device is critical on every router.Forms another firmware lacks return
no such callback, with a hint.Multipart uploads/downloads (backup, restore, firmware) are implemented for the plain protocol.
A per-device log
device_log action=record mac=... appends only what is new since the last record: online/offline,
router log lines, parental-control sites and blocked attempts. Run it on a timer for a continuous
history that outlives the router's own (daily) data, then read it with action=history.
Firmware quirks handled
Found against a live BE9300 (fw 1.2.4); each one is encoded in the catalog or the tools:
WPS:
option=connectstarts push-button pairing;pbc/pinonly poll the status. The router cancels WPS when the admin session logs out, sowps_pushstays logged in and polls until a device pairs or the window closes. Status replies take ~18 s.Guest Wi-Fi: only changed fields may be sent. A full write with blank
passwd_cycleis refused.DoH/DoT:
server_listmust be sent as a repeatedserver_list=field and included with every write ("no server found" otherwise). JSON wipes the list, andserver_list[]is refused.IPTV / link aggregation:
port_settingsmust always be sent as JSON, or the router returns HTTP 500. Saving IPTV restarts the network for about 40 s.OFDMA: on routers with the combined setting, the standalone switch is ignored. Use
ofdma_mimo(all/ofdma_only/disabled).IP-MAC binding: refused while the IP is DHCP-reserved for another MAC. The router drops custom names on bindings and reservations.
Speed limits are stored verbatim (
on/off). WPS wait time is read-only.LAN IPv6 address is recomputed by the router on every save.
MAC clone and WAN changes reconnect the WAN, and the ISP may assign a new public IP. Anything allowlisting your old IP (cloud firewalls, DNS-filter locations) will need updating.
Admin password fields are RSA-encrypted with per-field keys from the read. The server encrypts at send time, so the dry run's confirm token stays valid.
MLO network:
selected_bandsmust be sent with every write. A write without it switched the MLO network off.User-permission switches are accepted but ignored for a normal admin login (
no_effect).Eco mode takes
strong/medium/weak; DST and the 24-hour clock usedst_enable/hour24_enable.USB sharing is saved as ONE request (server name +
enable="on,off,off"for Samba/FTP/FTP-internet); per-service saves are refused. The server name can't be written on its own.Fields the router keeps when blanked (the DMZ address, the custom WAN MAC) don't count as a failed restore.
TP-Link DDNS has no refresh operation (it updates itself).
Known limitations
mesh action=pairis disabled. In testing, starting the satellite search and a WPS session in the same login locked a BE9300 up badly enough that a factory reset was needed. Pair satellites with the router's WPS button,wifi_extra action=wps_push, or the web UI.maintenance action=operation_mode(router ↔ AP/repeater) is implemented but was not switched live. With the router connected straight to an ISP box, AP mode can leave it unreachable.usb action=ejectis accepted by the router, but in testing the partitions kept reading as mounted until the drive was unplugged, so treat it as "safe to unplug" only after checking.Not yet exercised live (implemented from the web UI's code, covered by offline tests): firmware image upload and online update (no newer firmware was available), Time Machine, DDNS login, WPS client-PIN pairing, mesh satellite operations, adding WireGuard server accounts (the router refuses the format tried so far), parental-control profile edits and operation mode. Operations marked
uiornoneinrouter_catalogfall in this group.
Development
venv/bin/pytest -q # offline: a fake router; any socket/requests use fails the test
venv/bin/ruff check .docs/router/endpoints.txtlists every form the web UI references.tests/fixtures/shapes.jsonholds live field shapes (no values) for the readable forms. The catalog's writable fields are checked against it.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
30+ deterministic dev and delivery tools: linting, metrics, diagrams, model advice, AI-text checks.
BYOK AI router & FinOps control plane: audit token waste, check tool safety, and rank models.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables automation and management of TP-Link BE3600 routers through browser automation, supporting port forwarding configuration, network status monitoring, and device management without reverse-engineering the router's encryption.2MIT
- AlicenseBqualityBmaintenanceEnables 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.16MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseBqualityBmaintenanceEnables 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.39MIT