TP-Link Easy Smart Switch MCP

适用于 TP-Link 和 Mercury Easy Smart 交换机的 TypeScript + Bun MCP 服务器。它通过交换机 Web UI 工作，不依赖 SNMP。

默认目标：http://192.168.3.10

作为 Codex 插件安装

先安装 Bun，然后添加独立的 network-tools 市场和本插件：

codex plugin marketplace add qwe7002-ai/net-tool-plugins --ref main
codex plugin add tplink-easy-smart-switch-mcp@net-tool-plugins

安装后启动一个新的 Codex 任务，以便加载 MCP 工具和交换机管理技能。

Related MCP server: mcp-omada

已测试型号

当前实现已针对以下 Web UI 快照和只读状态调用进行了测试：

• 位于 192.168.3.10 的 TP-Link TL-SE2106，固件 1.8.1 Build 20251128 Rel.57341

• 位于 192.168.3.11 的 Mercury SE106 Pro，固件 1.0.0 Build 20240812 Rel.65021

其他 TP-Link 或 Mercury Easy Smart 交换机如果使用相同的 Web UI 页面和 CGI 端点，也可能可以工作，但尚未验证。

已确认的设备特性

• 管理界面可通过 HTTP 80 访问

• 登录表单提交到 POST /logon.cgi

• 登录字段为 username 和加密的 password

• 登录页面加载 /cryp_new.js

• 已知 Web UI 变量包括 g_product、g_year 和 encryptType

• 某些固件将请求令牌暴露为裸数字赋值（例如 g_tid=1320064778;），而不是带引号的字符串。其他页面可能只引用 top.g_tid，因此解析器必须区分赋值与引用。

工具

只读工具：

• get_switch_status：返回交换机状态摘要

• get_port_status：返回端口状态

• get_vlan_status：返回端口 VLAN、802.1Q VLAN、PVID 和 MTU VLAN 状态

• get_trunk_status：返回端口聚合/LAG 状态

• search_mac_address：查询 mac_address_search.cgi 查找单个 MAC 地址，并在交换机有条目时返回学习到的端口/VLAN

• analyze_topology：分析两台或多台级联交换机，并报告交换机间链路端口、上行/下行关系以及链路两端的 VLAN 关系

拓扑分析的工作原理是登录每台交换机，并查询 MAC 搜索 CGI 以获取对端交换机的管理 MAC。如果一台交换机在某个端口上报告了对端 MAC，则该端口被用作交换机间链路证据。当 MAC 搜索无法确认链路时，检测会回退到活动的 SFP/10G 端口对作为低置信度猜测，优先考虑 VLAN 重叠，并以实时流量作为决胜条件。这些 Easy Smart 交换机没有 LLDP，因此这种带内关联是可用的信号。

配置 CGI 工具：

• configure_mtu_vlan：从 VlanMtuRpm.htm 生成或提交 mtuVlanSet.cgi

• configure_port_vlan：从 VlanPortBasicRpm.htm 生成或提交 pvlanSet.cgi

• configure_8021q_vlan：从 Vlan8021QRpm.htm 生成或提交 qvlanSet.cgi

• configure_vlan_pvid：从 Vlan8021QPvidRpm.htm 生成或提交 vlanPvidSet.cgi

• configure_trunk_group：从 PortTrunkRpm.htm 生成或提交 port_trunk_set.cgi / port_trunk_display.cgi

• save_configuration：从 SavingConfigRpm.htm 生成或提交 POST savingconfig.cgi

配置工具默认 apply: false，这会返回 dry-run 请求预览且不提交任何内容。实际写入需要满足以下所有条件：

• apply: true

• confirm: "APPLY"

• 成功登录

• 通过 Web UI 规则校验

• 可读的 token/top.g_tid

安装

bun install

开发期间运行

bun run src/index.ts

构建二进制文件

Windows：

bun run build:win

当前平台：

bun run build

构建输出写入 dist/。

如果 MCP 客户端在 initialize 期间仍报告较旧的服务器版本，则其 command 可能指向旧的可执行文件。将其更新为 dist/tplink-easy-smart-switch-mcp.exe 并重启客户端。

调试 MCP

列出 MCP 工具：

bun run debug

调用交换机状态工具：

bun run debug -- --tool get_switch_status --host 192.168.3.10 --username admin --password your-password
bun run debug -- --tool get_switch_status --host 192.168.3.11

调用端口状态工具：

bun run debug -- --tool get_port_status --host 192.168.3.10 --username admin --password your-password

预览配置请求而不提交它们：

bun run debug -- --tool configure_mtu_vlan --params '{ "enabled": true }'
bun run debug -- --tool configure_port_vlan --params '{ "mode": "set", "vid": 1, "ports": "1,2" }'
bun run debug -- --tool configure_8021q_vlan --params '{ "mode": "set", "vid": 20, "name": "main", "untaggedPorts": "3", "taggedPorts": "5,6" }'
bun run debug -- --tool configure_vlan_pvid --params '{ "pvid": 20, "ports": "3" }'
bun run debug -- --tool configure_trunk_group --params '{ "mode": "set", "group": 1, "ports": "1,2" }'
bun run debug -- --tool save_configuration --params '{}'

页面示例

只读开发快照存储在：

• examples/tplink-192.168.3.10：位于 192.168.3.10 的 TP-Link Easy Smart 交换机

• examples/mercury-192.168.3.11：位于 192.168.3.11 的 Mercury SE106 Pro

它们包括 VLAN、聚合、配置备份/恢复、保存配置页面，以及 pvlan.js、qvlan.js 和 menuList.js。这些示例不包含 SessionID 值或密码。

你还可以发送原始 JSON-RPC：

bun run debug -- --raw '{ "jsonrpc": "2.0", "id": 99, "method": "tools/list", "params": {} }'

MCP 客户端示例

{
  "mcpServers": {
    "tplink-easy-smart-switch": {
      "command": "C:\\path\\to\\tplink-easy-smart-switch-mcp.exe",
      "env": {
        "TPLINK_HOST": "192.168.3.10",
        "TPLINK_USERNAME": "admin",
        "TPLINK_PASSWORD": "your-password"
      }
    }
  }
}

备注

页面内容由 DOM 解析器解析，并规范化为标题、表单、框架、链接、表格和文本摘要。状态数据主要从诸如 MainRpm.htm、VlanPortBasicRpm.htm、Vlan8021QRpm.htm、Vlan8021QPvidRpm.htm、VlanMtuRpm.htm 和 PortTrunkRpm.htm 等页面中的 JavaScript 变量提取。

在已测试的 TP-Link TL-SE2106 和 Mercury SE106 Pro 固件上，MacSearchRpm.htm 是一个搜索表单，而不是完整的转发表转储。因此，受支持的 MAC 功能是 search_mac_address，它遵循页面逻辑并使用 txt_macAddress_search、txt_vid_search 和 token 调用 mac_address_search.cgi。

令牌提取支持带引号的 g_tid、裸数字 g_tid 以及隐藏的 token 输入。捕获脚本在保存开发示例之前，会对带引号和裸数字的 g_tid 赋值进行脱敏处理。

配置 CGI 调用使用显式确认流程。开发和调试默认采用 dry-run。save_configuration 也是一种写入操作；它遵循 SavingConfigRpm.htm 的页面逻辑并使用 POST savingconfig.cgi，但除非明确确认，否则不会提交。