loliver1823/tplink-archer-be400-cli
GitHub: loliver1823/tplink-archer-be400-cli
面向 TP-Link Archer BE400 路由器的全功能 CLI 及 MCP 服务器，封装 192 个逆向 API 端点并支持 AI 助手直接交互管理路由器。
Stars: 0 | Forks: 0
# tplink-archer-be400-cli
专为 **TP-Link Archer BE400** 路由器打造的全功能 CLI + MCP 服务器 — 包含 192 个逆向工程的 API endpoint、37 个 CLI 命令、14 个用于 AI 集成的 MCP 工具（包括 Avira 家长控制域名屏蔽）。
## 安装
```
pip install git+https://github.com/loliver1823/tplink-archer-be400-cli.git
```
或克隆并在本地安装：
```
git clone https://github.com/loliver1823/tplink-archer-be400-cli.git
cd tplink-archer-be400-cli
pip install .
```
## 首次设置
```
tplink-be400 --setup
```
这会在 `~/.config/tplink-be400/config.toml` 路径下创建一个配置文件。请使用你的路由器 IP 和密码对其进行编辑：
```
[auth]
password = "YourRouterPasswordHere"
[routers.r1]
host = "http://192.168.0.1"
label = "Main Router"
# 支持多个路由器：
# [routers.r2]
# host = "http://192.168.0.202"
# label = "AP Mode Router"
```
你也可以完全跳过配置文件，直接传入凭据：
```
tplink-be400 --host 192.168.0.1 --password YourPassword status
```
## 用法
```
tplink-be400 [args...]
```
其中 `` 是你配置文件中的一个键（例如 `r1`）。
### 所有命令
| 命令 | 描述 |
|---------|-------------|
| `status` | 路由器完整概览（CPU、内存、WAN、客户端、固件） |
| `devices` | 列出所有已连接设备（有线 + 无线） |
| `wifi` | 所有频段的 WiFi 设置 + OFDMA、TWT、WPS、Smart Connect |
| `dhcp` | DHCP 配置、租约表和预留地址 |
| `wan` | WAN/互联网状态、协议、流量控制、双重 NAT 检测 |
| `lan` | LAN IP、子网、链路聚合、流量控制 |
| `firewall` | SPI 防火墙、IoT 安全、访问控制概览 |
| `access` | 访问控制详情（白名单/黑名单） |
| `parental` | 家长控制 / 按设备屏蔽域名 (Avira)：`parental [list \| devices \| block \| setfilter \| delete]` |
| `nat` | NAT 加速、虚拟服务器、端口触发、DMZ、ALG |
| `qos` | QoS 带宽控制、设备优先级列表、游戏加速器 |
| `ddns` | 动态 DNS（TP-Link、DynDNS、No-IP） |
| `upnp` | UPnP 状态和活跃服务映射 |
| `imb` | IP-MAC 绑定设置和 ARP 表 |
| `ports` | 物理端口状态（速度、双工、WAN/LAN） |
| `iptv` | IPTV、IGMP snooping、端口分配 |
| `guest` | 访客网络和强制门户设置 |
| `mesh` | EasyMesh 状态和拓扑 |
| `cloud` | TP-Link 云账户、固件更新检查 |
| `disk` | USB 磁盘信息和 Time Machine 设置 |
| `speedtest` | 测速结果和实时 WAN 吞吐量 |
| `rebootsched` | 定时重启设置 |
| `sharing` | USB/文件夹/媒体共享配置 |
| `logs [TYPE]` | 系统日志（过滤项：NETWORK、NAT、FIREWALL、DHCP 等） |
| `mode` | 操作模式（路由器/AP/中继器） |
| `firmware` | 固件版本、自动升级设置、配置备份 |
| `vpn` | VPN 配置（OpenVPN、PPTP、WireGuard） |
| `admin` | 管理（远程管理、HTTPS、恢复、邮件提醒） |
| `eco` | Eco 模式 / 节能设置 |
| `led` | LED 控制和夜间模式计划 |
| `time` | 时间/NTP 和 DST 设置 |
| `diag` | 路由器诊断 |
| `ipv6` | 完整的 IPv6 配置 |
| `routes` | 路由表（系统 + 静态路由） |
### 高级命令
| 命令 | 描述 |
|---------|-------------|
| `read ` | 从任意 endpoint 读取原始数据 |
| `write key=value ...` | 向任意 endpoint 写入设置 |
| `reboot` | 重启路由器（需要确认） |
| `endpoints` | 列出所有 192 个已知 API endpoint |
| `dump` | 将每个可读设置导出为 JSON 文件 |
| `monitor` | 持续的网络健康检查（ping + WAN 在线时间） |
| `discover` | 扫描 LAN 以查找 TP-Link 管理 UI；可选参数 `--subnet`、`--match-model`、`--no-auth-discovery`、`--skip-persist`（跳过写入 `config.toml`） |
### 示例
```
# 完整状态概览
tplink-be400 r1 status
# 列出已连接设备
tplink-be400 r1 devices
# 检查 WiFi 设置
tplink-be400 r1 wifi
# 查看防火墙规则
tplink-be400 r1 firewall
# 启用 WAN ping
tplink-be400 r1 write security/firewall wan_ping=on
# 设置 DMZ 主机
tplink-be400 r1 write nat/dmz enable=on ipaddr=192.168.0.100
# 家长控制：在一个设备上屏蔽 Smart-TV 广告/遥测域名
tplink-be400 r1 parental block TV-AdBlock D0-D0-03-D5-B4-E4 samsungads.com,samsungacr.com
tplink-be400 r1 parental # list profiles
# 读取原始 endpoint
tplink-be400 r1 read wireless/statistics
# 将所有内容导出为 JSON
tplink-be400 r1 dump
# 监控网络稳定性
tplink-be400 r1 monitor
```
## 频率限制 / 路由器稳定性
BE400 的 Web 服务器是一个资源有限的嵌入式系统。**高频的 API 调用会导致路由器崩溃**，引发看门狗重启且不留下任何崩溃日志。
安全使用指南：
- **单条命令始终是安全的。** 正常的 CLI 使用（一次执行一条命令）永远不会导致问题。
- **编写脚本**：在命令之间至少增加 2 秒的延迟。避免重复运行 `dump`。
- **会话流失**：每次 CLI 调用都会创建一个新的经过身份验证的会话（RSA 密钥交换 + AES 加密）。快速连续运行多条命令会在路由器上产生沉重的 CPU 负载。
- **`dump` 命令**按顺序读取所有 192 个 endpoint，耗时约 90 秒。不要在几分钟内多次运行它。
- **`monitor` 命令**被设计为使用 25 秒的轮询间隔。
如果路由器在繁重的 API 使用后无响应，请等待 60-90 秒，让其自动重启。
## MCP 服务器（AI 集成）
本软件包包含一个 MCP（Model Context Protocol）服务器，允许像 Claude 和 Cursor 这样的 AI 助手直接通过结构化工具与路由器交互，而不是使用 shell 命令。
### 为什么使用 MCP 而不是 Shell
- **持久会话** — 一次 RSA+AES 握手即可在所有调用中重用（避免可能导致路由器崩溃的会话流失）
- **内置频率限制** — API 调用之间最少间隔 1.5 秒，自动执行
- **结构化 JSON** — 每个响应都是干净的字典/列表，而不是需要解析的格式化文本
- **自动重连** — 如果会话超时，会静默重新进行身份验证
### MCP 安装
```
pip install git+https://github.com/loliver1823/tplink-archer-be400-cli.git
```
然后注册服务器。对于 **Cursor**，创建/编辑 `~/.cursor/mcp.json`：
```
{
"mcpServers": {
"tplink-be400": {
"command": "python",
"args": ["-m", "tplink_be400.mcp_server"]
}
}
}
```
对于 **Claude Desktop**，将其添加到你的 `claude_desktop_config.json` 中：
```
{
"mcpServers": {
"tplink-be400": {
"command": "python",
"args": ["-m", "tplink_be400.mcp_server"]
}
}
}
```
添加配置后重启你的 AI 客户端。该服务器读取的凭据与 CLI 一样，均来自 `~/.config/tplink-be400/config.toml`。
### MCP 工具（共 14 个）
| 工具 | 描述 | 是否写入？ |
|------|-------------|---------|
| `router_overview` | 一键仪表盘：固件、CPU、内存、WAN、WiFi 摘要、设备数量、互联网状态 | 否 |
| `list_devices` | 所有已连接的客户端，包含 hostname、IP、MAC、连接类型 | 否 |
| `get_setting` | 读取任何主题（"wifi"、"wan"、"firewall" 等）或原始 endpoint 名称；可选 `router` 键（`r1`、`r2` 等） | 否 |
| `change_setting` | 向 endpoint 写入 key=value 对，返回修改前后的 diff | **是** |
| `get_logs` | 系统日志，支持可选的类型过滤（NETWORK、FIREWALL、NAT 等） | 否 |
| `find_endpoints` | 按关键字搜索 192 个 endpoint 目录 | 否 |
| `discover_routers` | 扫描 LAN 以查找 TP-Link Web 管理界面；可选身份验证；除非使用 `skip_persist`，否则会将新的 `[routers.*]` 添加到 `~/.config/tplink-be400/config.toml` | **是** (本地文件) |
| `run_diagnostic` | 在一次调用中完成 Ping 测试 + 端口状态 + WAN 速度检测 | 否 |
| `reboot_router` | 重启，带有强制的 `confirm: true` 安全门 | **是** |
| `parental_profiles` | 列出 Avira 家长控制配置文件（ownerId、绑定的 MAC、屏蔽域名列表）和限制 | 否 |
| `parental_devices` | 列出家长控制已知的设备（名称、MAC、类型、在线状态） | 否 |
| `parental_block_domains` | 创建一个配置文件，为设备 MAC 屏蔽给定域名 —— 例如三星电视的广告/遥测。保持常规互联网正常（通过网关 DNS 同样屏蔽 HTTPS） | **是** |
| `parental_set_filter` | 替换现有配置文件（`owner_id`、`domains`）的屏蔽域名列表 | **是** |
| `parental_delete_profile` | 通过 `owner_id` 删除家长控制配置文件 | **是** |
### `get_setting` 主题
`get_setting` 工具接受聚合多个 endpoint 的高级主题名称：
`wifi`, `wan`, `lan`, `dhcp`, `firewall`, `parental`, `nat`, `qos`, `vpn`, `admin`, `mesh`, `ipv6`, `ddns`, `upnp`, `led`, `eco`, `time`, `firmware`, `disk`, `sharing`, `iptv`, `imb`, `cloud`, `logs`, `ports`, `routes`, `guest`
或者传入任何 endpoint 简称（例如 `wireless/ofdma`、`nat/dmz`）进行单次原始读取。使用 `find_endpoints` 搜索目录。
### MCP 示例
```
# AI 调用 router_overview → 获取完整的 dashboard 为 JSON 格式
router_overview()
→ { firmware: { model: "Archer BE400", version: "1.1.2 ..." }, performance: { cpu_percent: 11.0, memory_percent: 46.0 }, clients: { total: 20 }, wan: { ip: "180.150.x.x", uptime_human: "4h 23m" }, ... }
# AI 调用 get_setting 并指定 topic 为 "wifi" → 获取所有 WiFi 配置
get_setting(topic="wifi")
→ { data: { "wireless/wireless_2g": { ssid: "MyNetwork", channel: "6", ... }, ... } }
# AI 调用 change_setting → 更改设置并进行确认
change_setting(endpoint="security/firewall", settings={"wan_ping": "on"})
→ { success: true, changes: { wan_ping: { before: "off", after: "on" } } }
# AI 调用 find_endpoints → 搜索 catalog
find_endpoints(query="vpn")
→ { endpoints: [{ name: "openvpn/config", path: "admin/openvpn?form=config", operation: "read" }, ...] }
```
### 家长控制（按设备屏蔽域名）
BE400 基于 Avira 的家长控制通过 `parental_*` 工具暴露出来。每个“配置文件”（所有者）将一个或多个设备 MAC 绑定到一个屏蔽域名列表（最多 64 个域名）。屏蔽在网关处通过 DNS 操控执行，因此它也会断开到这些域名的 **HTTPS** 连接，同时保持设备的常规互联网完好无损。一个常见的用途是屏蔽 Smart-TV 的广告/遥测，而不影响网络的其余部分。
```
# 在一个设备上屏蔽 Samsung Smart TV 广告/遥测
parental_block_domains(
name="TV-AdBlock",
macs="D0-D0-03-D5-B4-E4",
domains="samsungads.com,samsungadhub.com,samsungacr.com",
)
→ { success: true, data: { ownerId: 0 } }
# 之后进行检查、编辑或移除
parental_profiles() # find the ownerId + current lists
parental_set_filter(owner_id="0", domains="samsungads.com,extra.com") # replaces the list
parental_delete_profile(owner_id="0") # removes the block
```
## 工作原理
该工具与路由器的内部 Web API 进行通信 —— 这与基于浏览器的管理面板使用的 API 相同。所有 endpoint 都是通过对路由器的 JavaScript bundle 进行逆向工程发现的。
身份验证使用 RSA + AES 加密（由 `tplinkrouterc6u` 库处理）。每个请求都通过与 Web UI 相同的加密通道进行。
## 依赖
- [tplinkrouterc6u](https://github.com/AlexandrErohin/TP-Link-Archer-C6U) — TP-Link 路由器 API 库
- [pycryptodome](https://github.com/Legrandin/pycryptodome) — RSA/AES 加密
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol SDK（用于 MCP 服务器）
## 兼容性
| 路由器 | 固件 | 状态 |
|--------|----------|--------|
| Archer BE400 v1.0 | 1.0.4 (2024) – v1.11.0 (2025) | 经过全面测试 |
| 其他 TP-Link 路由器 | — | 可能部分可用 |
## 许可证
MIT
标签：MCP, TP-Link, 云资产清单, 家庭网络, 网络设备管理, 逆向工具, 逆向工程