deco-mcp
You can inspect and carefully modify a TP-Link Deco mesh through MCP tools, with redaction, web fallback, lockout awareness, and graded write safety.
List available reads and writes, including write safety tiers.
Read individual router values, with secrets redacted by default.
Read secrets explicitly when needed via the unredacted read tool.
Get a mesh overview: nodes, backhaul type/signal, firmware, and online clients.
Take a full paced router snapshot of all known reads.
Check post-write lockout status without contacting the router.
Write settings with read-back confirmation, refusing unverified writes unless explicitly allowed.
Fall back to the local web interface for reads it supports.
Respect the shared lockout so callers wait instead of hammering the router.
When run read-only, expose no write tools.
Provides local control of TP-Link Deco mesh routers without cloud or app, enabling mesh overview (nodes, backhaul type, signal strength, firmware, connected clients), reading router settings such as DHCP reservations, port forwards, DNS servers, and WPS, and performing graded write operations like LED night mode with read-back verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@deco-mcp Give me an overview of my mesh and flag any weak wireless backhaul."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
deco-local
Local control of TP-Link Deco mesh routers: no cloud, no app. A Python library, a small CLI, and an MCP server so Claude (or any MCP client) can look at your mesh and, carefully, change it.
(an illustration)
You: Which of my Deco nodes is on wireless backhaul, and how good is its link?
Claude: (mesh_overview) One node is: "Attic", an M5 hanging off "Hallway" over 5 GHz and
2.4 GHz, both at signal 2 of 3. The other four are wired. Attic has 3 clients...What it does that others don't
Two interfaces, one answer. The Deco has a control port (the TMP protocol the app uses, SSH on port 20001) and a local web interface on port 80. The control port can do far more, but it locks up: for 60-90 s after every write, and sometimes much longer. When it does, the reads the web interface also offers (nodes, clients, WAN, CPU/memory) come from there instead, reshaped into the same names and fields. Every read says which interface answered.
Writes are graded by evidence. Each write is
verified(proven live with a before/after read-back),upstream(seen in real app captures by pydeco-tmp, not re-tested),noop(proven to ACK and do nothing, like HomeShield's toggle) orinferred(an opcode-numbering guess). Anything not verified is refused unless you opt in, and every write returns the router's read-back, not just its ACK.It knows the router's moods. After a write the router drops the control port for ~60-90 s. Connecting during that window keeps it shut longer, so a shared lockout makes every caller on the machine (MCP server, scripts) wait instead of hammering it.
Safe to hand to an AI. Secrets are redacted by default, refusals say why (so the model asks you instead of guessing), and
DECO_MCP_READONLY=1gives a server with no write tools at all, for anything unattended.
Related MCP server: archer-router-mcp
Tested on
Deco X55 (hardware 1.0, firmware 1.11.1) as the main router, with M5 satellites.
The control port is on the main Deco only; it reports the whole mesh. Other Deco models very likely speak the same protocol (the app is the same), but they haven't been tried. If you try one, please open an issue with what worked.
Credentials
The control port logs in with your TP-Link account email and password, the ones you use in the Deco
app. The Deco checks them itself, locally; nothing is sent to TP-Link's cloud. The web interface uses
the same password on app-managed Decos (DECO_WEB_PASSWORD if yours differs).
Variable | |
| the main Deco's LAN address (default |
| TP-Link account email |
| TP-Link account password |
| optional, if the web interface password differs |
|
|
| optional; lockout state, the web session and the client-to-node map (default |
Use it with Claude
Needs uv (uvx runs it without installing anything permanently). Or pip install deco-local, which gives the deco and deco-mcp commands.
Claude Code:
claude mcp add deco -e DECO_HOST=192.168.68.1 -e DECO_EMAIL=you@example.com -e DECO_PASSWORD='...' \
-- uvx --from deco-local deco-mcpAdd -e DECO_MCP_READONLY=1 for a read-only server.
Claude Desktop: Settings, Developer, Edit Config, and add:
{
"mcpServers": {
"deco": {
"command": "uvx",
"args": ["--from", "deco-local", "deco-mcp"],
"env": {
"DECO_HOST": "192.168.68.1",
"DECO_EMAIL": "you@example.com",
"DECO_PASSWORD": "...",
"DECO_MCP_READONLY": "1"
}
}
}
}Leave out DECO_MCP_READONLY if you want Claude to be able to change settings. It will still refuse
unverified writes unless you say so.
Things to ask:
"Give me an overview of my mesh." / "Which node is my laptop on, and how's its signal?"
"Is any node on wireless backhaul? How strong is it?"
"What firmware are my Decos on?" / "Show my DHCP reservations and port forwards."
"Which clients are on 2.4 GHz?" / "What DNS servers is the router using?"
"Turn the LED night mode on." (a verified write: Claude reads the setting, changes one field, writes it, and shows you the read-back)
Tools
Tool | |
| nodes (online, backhaul, signal, upstream, firmware, client count) and online clients (node, band, signal) |
| one named read, secrets redacted; falls back to the web interface where it can |
| every read name, and which the web fallback covers |
| whether the router is still applying a write (no router contact) |
| a read with secrets included (not in read-only mode) |
| every read in one paced pass, over a minute (not in read-only mode) |
| every write with its tier and note (not in read-only mode) |
| a write, with the read-back (not in read-only mode) |
Library
from deco_local import DecoClient, WRITE
with DecoClient("192.168.68.1", "you@example.com", "password") as deco:
nodes = deco.get("device_list")["device_list"]
led = deco.get("led_schedule")
deco.set("led_set", dict(led, enable_night_mode=True), confirm=True) # verified write
print(deco.get("led_schedule")["enable_night_mode"]) # read it back
# the control port is now locked ~60-90 s; deco_local.busy.wait() blocks until it is back
from deco_local import web
reads = web.snapshot("192.168.68.1", "password", ["device_list", "client_list"]) # web interfaceThe web interface is slow and its CPU climbs under a burst of requests, so web.snapshot spaces them gap seconds apart (default 1.5).
Which node each client is on costs one request per node, so only probes nodes (default 2) are re-asked per call, rotating: a roam
shows up after a few calls, not at once. A new client, or a map older than 6 h, rebuilds it all.
DecoClient.set needs confirm=True, and allow_unverified=True for anything but a verified write.
Reads come back in the router's own shapes; deco_local/tmp.py lists every read and write.
CLI
deco reads # every read name
deco writes # every write and its tier
deco read device_list wps # over the control port (JSON)
deco read --web client_list # over the web interface
deco status # post-write lockout (no router contact)The CLI only reads. Writes go through the library or the MCP server.
Writes: what's known
Only led_set is verified so far. 12 more are upstream (seen in app captures, including UPnP,
DoH, DHCP reservations, DDNS, IPv6, WPS, 802.11r, DNS servers), one is a proven no-op, and the rest are
guesses from the opcode numbering. Verifying one is simple and the most useful contribution: read the
setting, write a harmless change, read it back, write the original back, and open an issue or PR
moving it to verified, with your model and firmware. Avoid WAN-affecting ones (ipv6_set,
internet_backup_set, mac_clone_set, operation_mode_set) unless you can get to the router
another way if it goes wrong.
The lockout
Measured on the X55: a write ACKs and reads back within ~3 s; then the control port closes ~5-14 s later and stays closed until ~64-95 s after the write. Probing every 0.5 s kept it shut longer, so the watcher probes every 5 s. The control port has also been seen to stay closed for 45+ min after a node reboot from the app, while the web interface kept working; that is what the fallback is for. The lock is a small state file, so every process on the machine respects it. A short-lived script's watcher dies with it; the lock then simply expires after 150 s.
No warranty
This talks to your router with undocumented protocols. Reads are harmless; writes change real settings, and unverified ones may do something unexpected. MIT licensed, as is.
Credits
Built on two projects' protocol work. No code from either is used here; the clients are reimplementations from their descriptions:
mthsg/pydeco-tmp (MIT): the Deco TMP protocol (SSH transport, framing, login, opcode tables) and the app-capture list behind the
upstreamtier.tplinkrouterc6u (GPL-3.0): the encrypted login of TP-Link's local web interface. Compared line by line: no code in common, only the protocol.
License
MIT
Available Tools
8 toolsget_router_dataB
Read one named value from the Deco (see list_reads). Secrets (Wi-Fi passwords, VPN private keys) are redacted. Returns {source, result} and, when the web interface answered, why.
Inputs: name (required).
get_router_data_unredactedA
Like get_router_data but includes secrets (e.g. Wi-Fi passwords, a WireGuard private key). Only use this when the user specifically needs the secret, and don't write it anywhere without asking.
Inputs: name (required).
list_readsA
Every read this router exposes (client list, Wi-Fi config, QoS, port forwarding, DHCP, VPN config, firmware, ...), and which of them the web-interface fallback can also provide. Use get_router_data to read one.
Inputs: no named parameters.
list_writesA
Every write this server can attempt: verified (proven live with a read-back), upstream (seen in real app captures, not re-tested), noop (proven to do nothing) or inferred (opcode-numbering guess), with a note.
Inputs: no named parameters. Returns: result
lockout_statusA
Whether the router is still applying a write (control port locked), and how the last lockout went. No router contact.
Inputs: no named parameters.
mesh_overviewA
The mesh at a glance: each node (name, model, online, wired or wireless backhaul with signal 0-3, upstream node, IP, firmware, client count) and each online client (name, IP, node, band, signal). Two reads, with the web-interface fallback.
Inputs: no named parameters.
router_snapshotA
Read every known value in one pass (~70 reads, paced 1 s apart, so over a minute). Heavy on the router; use get_router_data for what you actually need.
Inputs: no named parameters.
write_router_settingA
Write a setting (see list_writes). Pass the whole object as read from the matching read, with
your change made (e.g. read led_schedule, flip enable_night_mode, send it to led_set). Refuses
unverified writes unless allow_unverified=True -- ask the user first. Returns the read-back
(after); report that, not just success. The router then locks for ~60-90 s.
Inputs: name (required), params (required), allow_unverified.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The read/write catalogs are cleanly separated from the execute tools, and lockout_status is unique. Overlap remains between get_router_data and get_router_data_unredacted (a flag could have been a parameter) and to a lesser degree between mesh_overview and router_snapshot, so an agent can occasionally hesitate.
All names are descriptive snake_case with no style mixing, and most start with clear verbs (list_, get_, write_). Three names are noun phrases (mesh_overview, router_snapshot, lockout_status), so the verb_noun pattern is not fully uniform.
Eight tools for a router-management server is well within the ideal range. Each has a distinct role: catalog, read, write, overview, lockout status, snapshot, and secrets access.
Reads are comprehensively enumerated via list_reads and router_snapshot, and writes via list_writes plus read-modify-write. The surface lacks explicit action tools for non-setting operations (e.g. reboot or firmware action) if those exist, but core lifecycle coverage is strong.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Network, domain and website diagnostics for AI clients via MCP.
See which AI models fall for traps in everyday jobs, and check or scan any MCP server, skill or package before your agent installs it. No sign-in; read-only; returns structured data.
Uptime, SSL, DNS and domain monitoring you can talk to from Claude or any MCP client.
Related MCP Servers
- 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
- AlicenseNot gradedqualityBmaintenanceEnables an MCP client such as Claude Code to inspect and change a stock OpenWrt 25.12+ router over SSH, covering system status, logs, clients, firewall, packages, services, and WireGuard peers. Configuration edits are staged, checked, and armed with an automatic rollback that survives a reboot, all behind deny-by-default per-client grants, an audit log, and masked secrets.1MIT
- AlicenseAqualityBmaintenanceEnables LLM clients to inspect and manage a TP-Link Deco mesh Wi-Fi network, covering mesh nodes, connected devices, SSIDs and radio settings, internet status, blocked clients, and DHCP address reservations. Runs entirely against the router on the local network without any cloud account.1554 PyPIMIT