Content
# tplinkcli
> next time imma flash my own openwrt so i dont have to do this shit
A CLI + MCP tool for TP-Link Archer/AX routers, so you can manage the router from the terminal instead of the web UI. Reverse-engineered from the site's JS.
## Install
With [uv](https://docs.astral.sh/uv/), install it as a global tool - puts `tplink` and
`tplink-mcp` on your PATH:
```sh
uv tool install '.[mcp]' # from a local checkout
# uv tool install 'tplinkcli[mcp]' # once published to PyPI
```
Then put your credentials in `~/.config/tplink/.env`:
```sh
ROUTER_IP=192.168.0.1
ROUTER_USERNAME=admin
ROUTER_PASSWORD=your-router-password
```
Credentials are also read from environment variables, a project-local `.env`, or a file
pointed to by `$TPLINK_ENV` (precedence, low → high: user config → project `.env` →
`$TPLINK_ENV` → env vars → `--host/--password` flags).
## CLI
The router only allows **one admin session at a time**, so each `tplink <command>` logs
in, runs, and logs out, releasing the session for the web UI. For several commands in a
row, use the interactive session instead:
```sh
tplink # interactive session:
tplink> clients
tplink> raw status?form=internet --op read # no quoting needed in here
tplink> exit # logs out
```
One-shot commands:
```sh
tplink clients # connected devices with IP + MAC
tplink status # mode, WAN IP, uptime, CPU/mem, SSIDs
tplink wifi # SSID + on/off per band (passwords hidden; --reveal-secrets)
tplink stats # per-client wireless signal (dBm), PHY rate, band
tplink ports # physical ethernet port link status
tplink dhcp # DHCP leases
tplink watch clients|leases # live poll: print join/leave/IP-change diffs (Ctrl-C to stop)
tplink dhcp-config # DHCP server pool / lease time / DNS
tplink reservations # DHCP address reservations
tplink syslog --level ERROR --limit 50 # system log (DHCP/SAE/DFS events)
tplink radio 5g # radio settings for a band (channel, width, security)
tplink wifi-adv 5g # advanced: WMM, beacon/DTIM/RTS, tx power, OFDMA, TWT, band steering
tplink firmware # firmware/hardware version + cloud update check
tplink wan # WAN/internet status (JSON)
tplink ipv6 # IPv6 WAN + LAN status
tplink session # session age / login count
tplink dump -o snap.json # full-state snapshot (config-drift diffing)
tplink reboot # reboot (asks to confirm; --yes to skip)
tplink raw 'status?form=client_status' --op load --json # call any endpoint directly
```
Quote the `raw` path in your shell (the `?` is a glob) — not needed inside the interactive
session. Add `--json` to most commands for machine-readable output.
## MCP server
Exposes the router to an AI agent — 24 tools including `get_syslog`, `get_client_stats`,
`get_dhcp_settings`/`set_dhcp_settings`, `list_reservations`/`add_reservation`,
`get_wifi_radio`/`set_wifi_channel`/`set_wifi_security`, `get_wps`/`set_wps`,
`get_guest_network`/`set_guest_network`, `session_info`, `list_endpoints`, and `raw_request`.
Wi-Fi passwords are redacted by default (`reveal_secrets=true` to opt in); radio-restarting
writes require `confirm=true`.
```sh
tplink-mcp
```
Example Claude Code config (credentials via `~/.config/tplink/.env` or inline `env`):
```json
{
"mcpServers": {
"tplink": {
"command": "tplink-mcp",
"env": { "ROUTER_IP": "192.168.0.1", "ROUTER_PASSWORD": "..." }
}
}
}
```
## Development
Work on the code from a checkout without installing globally:
```sh
uv sync --extra mcp # dev tools (pytest) are in the default dependency group
uv run pytest -q # crypto tests run offline (synthetic vectors only)
uv run tplink status # run against the router without a global install
uv tool install --force '.[mcp]' # reinstall the global tool after changes
```
