Skip to main content
Glama

deco-mcp

An MCP server for TP-Link Deco mesh routers. It lets an AI assistant such as Claude Code read the router and manage DHCP address reservations, using the router's own local web API.

  • List connected clients with name, MAC, IP and the node they're on, see who is using the bandwidth, and rename clients.

  • List, add, change and remove DHCP address reservations, and audit them for clashes and drift.

  • Read status and settings: mesh nodes, model, firmware, internet, WAN, LAN, Wi-Fi and more, with secrets redacted.

  • Reboot the mesh (off by default).

Everything stays on your network. The server talks only to the router's address, over the same encrypted login the Deco web UI uses, and needs no TP-Link cloud account access.

Not affiliated with TP-Link. This uses an undocumented local API through the community library tplink-deco-api. Firmware updates can change or break it.

How it works

Claude Code ──HTTP + bearer token──▶ deco-mcp (small LXC/VM) ──HTTPS, encrypted login──▶ Deco router
  • The server is the standard library's HTTP server speaking MCP's streamable HTTP transport with plain JSON responses: no SSE and no sessions. The whole package is under 600 lines, with no web framework.

  • Each tool call logs in to the router, does one job and drops the session. Calls run one at a time, because the Deco allows only one admin session.

  • Its one dependency is tplink-deco-api, which itself needs only cryptography.

Tested on a three-unit Deco M4R v2 mesh running firmware 1.8.2. The library has also been checked against a BE65 by its author. Other models that use the same web UI should work. Please open an issue with your model, whether it works or not.

Related MCP server: miwifi-mcp

Tools

Tool

Does

Changes the router

deco_status

Mesh nodes (model, firmware, role, IP), internet status, CPU and memory, and the DHCP pool where the firmware exposes it (not on the M4R)

no

deco_clients

Clients with name, MAC, IP, online state, connection and node. online_only filter

no

deco_reservations

Reservations (MAC to IP), each with the device's name and current IP

no

deco_config

Router settings (system, WAN, LAN, IPv6, Wi-Fi, NAT, services, security). Secret-looking fields are redacted on the server. Forms the firmware serves only to the Deco app are listed as unavailable

no

deco_traffic

Current upload and download rate per online client, busiest first, with totals. Seems to count internet traffic only, not traffic inside the LAN

no

deco_audit

Checks reservations for duplicates, reserved IPs used by another device, devices not on their reserved IP, reservations for unknown or offline devices, and generic client names. Pass expected (MAC, IP, name, static), for example from a hypervisor's guest list, to also check that each device has the reservation it should and that static IPs aren't taken

no

deco_client_rename

Rename a client as shown in the Deco app

yes

deco_reservation_add

Add a reservation. Refuses duplicates and addresses outside the LAN

yes

deco_reservation_change

Change the IP of a reservation

yes

deco_reservation_remove

Remove a reservation

yes

deco_reboot

Reboot every node. Needs DECO_ALLOW_REBOOT=1 and confirm: "reboot the whole mesh"

yes

Input is checked before any request reaches the router: MACs must be valid, and IPs must be usable addresses inside the LAN that aren't the router itself. Every change is logged at WARNING with a WRITE prefix.

A new or changed reservation takes effect when the device next renews its DHCP lease or reconnects.

Install

Run it on an always-on machine on the same LAN as the router. There are two ways: Docker, or a plain systemd service on a small Proxmox LXC or VM (1 core, 512 MB RAM, 4 GB disk).

Docker

The image is built from this repo. It runs Python 3.14 as an unprivileged user on a read-only filesystem, and installs dependencies from deploy/requirements.lock with --require-hashes. The secrets are Docker secret files.

git clone https://github.com/nitin23c/deco-mcp.git
cd deco-mcp
mkdir -p secrets && chmod 700 secrets
docker compose build
docker run --rm deco-mcp:local --new-token > secrets/mcp_token
(umask 077; printf 'Router password: '; stty -echo; read -r p; stty echo; echo
 printf '%s' "$p" > secrets/deco_password)
chmod 644 secrets/*      # the container user must read them; the 700 folder keeps others out
docker compose up -d
docker compose ps        # STATUS shows "healthy"

Edit compose.yaml first: set DECO_HOST, and set MCP_ALLOW_NETS to your LAN. Clients on the LAN reach the container with their own address. Requests from the Docker host itself arrive from Docker's bridge network, which is why 172.16.0.0/12 is in the default list. The endpoint is http://<docker-host>:8080/mcp.

The image's health check (--healthcheck) only checks that the server refuses an unauthenticated request. It needs no secrets and never contacts the router.

systemd

It needs Python 3.14, which the installer fetches with uv. On a Debian or Ubuntu host, as root:

git clone https://github.com/nitin23c/deco-mcp.git
cd deco-mcp
./deploy/install.sh          # packages, uv, Python 3.14, pinned library, systemd unit
deco-mcp-setup               # router address and password (hidden), makes a token
systemctl start deco-mcp
journalctl -u deco-mcp -n 5  # "deco-mcp 0.2.0 on 0.0.0.0:8080, ..."

deploy/install.sh installs the library from deploy/requirements.in, pinned to a reviewed git commit, and compiles a hashed lock from it. It's safe to run again to update.

Check the login without starting the server:

set -a; . /etc/deco-mcp.env; set +a
/opt/deco-mcp/venv/bin/python -I -m deco_mcp --check

The router password

Deco routers have no separate local admin account. The web UI at https://<router> logs in as admin with the owner's password, the one used to sign in to the Deco app. deco-mcp-setup asks for it without echoing it and stores it only in /etc/deco-mcp.env (mode 600, root). systemd reads that file before dropping to the unprivileged deco-mcp user.

Run deco-mcp-setup again after changing the password. --new-token replaces the token, and --print-token prints it.

Configuration

All settings are environment variables: in /etc/deco-mcp.env for systemd, or in compose.yaml for Docker. Each secret can instead be read from a file by adding _FILE to its name (DECO_PASSWORD_FILE, MCP_TOKEN_FILE), which is how Docker secrets work.

Variable

Default

Meaning

DECO_HOST

192.168.68.1

Router address (the Deco default)

DECO_USERNAME

admin

Login user. Leave as admin

DECO_PASSWORD

(required)

Owner password

DECO_LAN

DECO_HOST/24

Network that reserved IPs must be inside

DECO_TIMEOUT

15

Seconds per router request

DECO_READ_ONLY

0

1 hides every tool that changes the router

DECO_ALLOW_REBOOT

0

1 offers deco_reboot

MCP_TOKEN

(required)

Bearer token, at least 32 characters

MCP_BIND

127.0.0.1

Listen address. deco-mcp-setup and the Docker image use 0.0.0.0

MCP_PORT

8080

Listen port. The endpoint is /mcp

MCP_ALLOW_NETS

loopback and DECO_LAN

Comma-separated CIDRs allowed to connect

Connect Claude Code

Store the token in the macOS Keychain (paste it at the hidden prompt):

security add-generic-password -a deco-mcp -s deco-mcp-token -w

Add the server for your user, with a headersHelper that reads the token from the Keychain, so the token isn't stored in any config file:

claude mcp add-json --scope user deco '{
  "type": "http",
  "url": "http://<server-ip>:8080/mcp",
  "headersHelper": "/path/to/deco-mcp/examples/mcp-headers.sh"
}'

Then make Claude Code always ask before a change. Merge examples/claude-settings.json into ~/.claude/settings.json: read tools run without a prompt, and the write tools always ask. On Linux, replace the helper with one that reads the token from your own secret store.

Other MCP clients that support streamable HTTP and custom headers work the same way: send Authorization: Bearer <token>.

Security

Read this before exposing anything.

  • The server holds your router admin password. Anyone with root on the host running it, or on its hypervisor, can read it. Give it its own small container.

  • Plain HTTP. The token travels unencrypted across the LAN. If your LAN isn't trusted, put the server behind a TLS reverse proxy (Traefik, Caddy, nginx) and keep MCP_BIND=127.0.0.1.

  • Access control: a source-address allowlist (MCP_ALLOW_NETS), then a constant-time bearer token check. Any request carrying an Origin header is refused, so a web page in your browser can't reach the server through DNS rebinding. Bodies are capped at 64 KB.

  • Never forward the port to the internet.

  • The router's certificate isn't checked. Decos use self-signed certificates, so the library turns off certificate checks. A device already on your LAN could pose as the router and capture the login.

  • Writes need consent. Write tools are marked destructiveHint, and their descriptions tell the model to get your yes first. The real safeguard is your client's permission settings, so set the write tools to ask (see above), or run with DECO_READ_ONLY=1.

  • Dependency pinning. deploy/requirements.in pins tplink-deco-api to a commit that was read in full (about 1,950 lines: one network call site, which posts only to the configured router; no eval, exec or subprocess; the PyPI source matched the git tag). Review the diff before bumping it.

  • The systemd unit runs as an unprivileged user with no capabilities, a read-only system, private /tmp, and other hardening.

Report security problems privately through GitHub's Report a vulnerability button. Please don't open a public issue.

Command line

python -m deco_mcp (or deco-mcp) starts the server. Other options: --check logs in once and prints the mesh nodes, --new-token prints a random token, --healthcheck exits 0 if the local server is answering, and --version prints the version.

Development

uv sync            # Python 3.14 + dev tools
uv run pytest      # runs against a fake router; never touches a real one

Licence

MIT. See LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    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
      B
      quality
      B
      maintenance
      Enables 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.
      16
      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