TP-Link Easy Smart Switch MCP

TypeScript + Bun MCP server for TP-Link and Mercury Easy Smart switches. It works through the switch Web UI and does not depend on SNMP.

Default target: http://192.168.3.10

Tested Models

The current implementation has been tested against these Web UI snapshots and read-only status calls:

TP-Link TL-SE2106 at 192.168.3.10, firmware 1.8.1 Build 20251128 Rel.57341
Mercury SE106 Pro at 192.168.3.11, firmware 1.0.0 Build 20240812 Rel.65021

Other TP-Link or Mercury Easy Smart switches may work if they use the same Web UI pages and CGI endpoints, but they have not been verified yet.

Confirmed Device Traits

Management UI is available on HTTP 80
Login form posts to POST /logon.cgi
Login fields are username and encrypted password
Login page loads /cryp_new.js
Known Web UI variables include g_product, g_year, and encryptType
Some firmware exposes the request token as a bare numeric assignment such as g_tid=1320064778; instead of a quoted string. Other pages may only reference top.g_tid, so parsers must distinguish assignments from references.

Tools

Read-only tools:

get_switch_status: Return a switch status summary
get_port_status: Return port status
get_vlan_status: Return port VLAN, 802.1Q VLAN, PVID, and MTU VLAN status
get_trunk_status: Return port trunking/LAG status
search_mac_address: Query mac_address_search.cgi for one MAC address and return the learned port/VLAN when the switch has an entry
analyze_topology: Analyze two or more cascaded switches and report the inter-switch link port, the upstream/downstream relationship, and the VLAN relationship across the link

Topology analysis works by logging into each switch and querying the MAC search CGI for the peer switch's management MAC. If a switch reports the peer MAC on a port, that port is used as inter-switch link evidence. When MAC search cannot confirm the link, detection falls back to active SFP/10G port pairs as a low-confidence guess, preferring VLAN overlap and using live traffic as a tiebreaker. These Easy Smart switches have no LLDP, so this in-band correlation is the available signal.

Configuration CGI tools:

configure_mtu_vlan: Generate or submit mtuVlanSet.cgi from VlanMtuRpm.htm
configure_port_vlan: Generate or submit pvlanSet.cgi from VlanPortBasicRpm.htm
configure_8021q_vlan: Generate or submit qvlanSet.cgi from Vlan8021QRpm.htm
configure_vlan_pvid: Generate or submit vlanPvidSet.cgi from Vlan8021QPvidRpm.htm
configure_trunk_group: Generate or submit port_trunk_set.cgi / port_trunk_display.cgi from PortTrunkRpm.htm
save_configuration: Generate or submit POST savingconfig.cgi from SavingConfigRpm.htm

Configuration tools default to apply: false, which returns a dry-run request preview and submits nothing. Real writes require all of the following:

apply: true
confirm: "APPLY"
Successful login
Web UI rule validation passed
A readable token/top.g_tid

Install

bun install

Run During Development

bun run src/index.ts

Build A Binary

Windows:

bun run build:win

Current platform:

bun run build

Build output is written to dist/.

If an MCP client still reports an older server version during initialize, its command probably points to an old executable. Update it to dist/tplink-easy-smart-switch-mcp.exe and restart the client.

Debug MCP

List MCP tools:

bun run debug

Call the switch status tool:

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

Call the port status tool:

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

Preview configuration requests without submitting them:

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 '{}'

Page Samples

Read-only development snapshots are stored in:

examples/tplink-192.168.3.10: TP-Link Easy Smart switch at 192.168.3.10
examples/mercury-192.168.3.11: Mercury SE106 Pro at 192.168.3.11

They include VLAN, trunking, configuration backup/restore, save-configuration pages, plus pvlan.js, qvlan.js, and menuList.js. These samples do not contain SessionID values or passwords.

You can also send raw JSON-RPC:

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

MCP Client Example

{
  "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"
      }
    }
  }
}

Notes

Page content is parsed with a DOM parser and normalized into title, form, frame, link, table, and text summaries. Status data is mainly extracted from JavaScript variables in pages such as MainRpm.htm, VlanPortBasicRpm.htm, Vlan8021QRpm.htm, Vlan8021QPvidRpm.htm, VlanMtuRpm.htm, and PortTrunkRpm.htm.

On the tested TP-Link TL-SE2106 and Mercury SE106 Pro firmware, MacSearchRpm.htm is a search form rather than a full forwarding-table dump. The supported MAC feature is therefore search_mac_address, which follows the page logic and calls mac_address_search.cgi with txt_macAddress_search, txt_vid_search, and token.

Token extraction supports quoted g_tid, bare numeric g_tid, and hidden token inputs. The capture script redacts both quoted and bare g_tid assignments before saving development samples.

Configuration CGI calls use an explicit confirmation flow. Development and debugging default to dry-run. save_configuration is also a write action; it follows the page logic from SavingConfigRpm.htm and uses POST savingconfig.cgi, but it does not submit unless explicitly confirmed.

tplink-easy-smart-switch-mcp