内容
# tplinkcli
> 下次我会刷自己的 OpenWRT，这样我就不用做这件事了
用于 TP-Link Archer/AX 路由器的 CLI + MCP 工具，您可以通过终端管理路由器，而不是通过网页界面。从网站的 JS 反向工程而来。
## 安装
使用 [uv](https://docs.astral.sh/uv/)，将其安装为全局工具 - 将 `tplink` 和 `tplink-mcp` 放在您的 PATH 中：
```sh
uv tool install '.[mcp]' # 从本地 checkout
# uv tool install 'tplinkcli[mcp]' # 发布到 PyPI 后
```
然后将您的凭证放在 `~/.config/tplink/.env` 中：
```sh
ROUTER_IP=192.168.0.1
ROUTER_USERNAME=admin
ROUTER_PASSWORD=您的路由器密码
```
凭证也可以从环境变量、项目本地 `.env` 或 `$TPLINK_ENV` 指向的文件中读取（优先级，低 → 高：用户配置 → 项目 `.env` → `$TPLINK_ENV` → 环境变量 → `--host/--password` 标志）。
## CLI
路由器每次只允许 **一个管理员会话**，因此每个 `tplink <command>` 都登录、运行并退出，释放会话给网页界面。对于连续的多个命令，请改用交互式会话：
```sh
tplink # 交互式会话：
tplink> clients
tplink> raw status?form=internet --op read # 这里不需要引号
tplink> exit # 退出登录
```
一次性命令：
```sh
tplink clients # 已连接设备，带 IP + MAC
tplink status # 模式，WAN IP，运行时间，CPU/内存，SSID
tplink wifi # SSID + 每个频段的开启/关闭（密码隐藏；--reveal-secrets）
tplink stats # 每个客户端的无线信号（dBm），PHY 速率，频段
tplink ports # 物理以太网端口链接状态
tplink dhcp # DHCP 租约
tplink watch clients|leases # 实时轮询：打印加入/离开/IP 更改的差异（Ctrl-C 停止）
tplink dhcp-config # DHCP 服务器池 / 租约时间 / DNS
tplink reservations # DHCP 地址保留
tplink syslog --level ERROR --limit 50 # 系统日志（DHCP/SAE/DFS 事件）
tplink radio 5g # 频段的无线电设置（频道，宽度，安全）
tplink wifi-adv 5g # 高级：WMM，信标/DTIM/RTS，tx 功率，OFDMA，TWT，频段引导
tplink firmware # 固件/硬件版本 + 云更新检查
tplink wan # WAN/互联网状态（JSON）
tplink ipv6 # IPv6 WAN + LAN 状态
tplink session # 会话年龄 / 登录次数
tplink dump -o snap.json # 全状态快照（配置漂移差异）
tplink reboot # 重启（询问确认；--yes 跳过）
tplink raw 'status?form=client_status' --op load --json # 直接调用任何端点
```
在您的 shell 中引用 `raw` 路径（`?` 是通配符）- 在交互式会话中不需要。 为大多数命令添加 `--json` 以获取机器可读的输出。
## MCP 服务器
将路由器公开给 AI 代理 — 24 个工具，包括 `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` 和 `raw_request`。Wi-Fi 密码默认被编辑（`reveal_secrets=true` 以选择加入）；无线电重启写入需要 `confirm=true`。
```sh
tplink-mcp
```
Claude Code 配置示例（凭证通过 `~/.config/tplink/.env` 或内联 `env`）：
```json
{
"mcpServers": {
"tplink": {
"command": "tplink-mcp",
"env": { "ROUTER_IP": "192.168.0.1", "ROUTER_PASSWORD": "..." }
}
}
}
```
## 开发
在本地 checkout 上开发代码，而不全局安装：
```sh
uv sync --extra mcp # 开发工具（pytest）在默认依赖组中
uv run pytest -q # 加密测试离线运行（仅合成向量）
uv run tplink status # 在没有全局安装的情况下针对路由器运行
uv tool install --force '.[mcp]' # 更改后重新安装全局工具
```
