tplink-easysmart-mcp

A local, browser-free MCP server for the TP-Link Easy Smart family of managed PoE switches (developed against the TL-SG1016PE). It speaks the switch's HTML/*.cgi web protocol directly — no headless browser at runtime — so an MCP client (Claude, or any MCP host) can read port, statistics and PoE status and power-cycle a wedged PoE camera without anyone opening the switch's web UI.

It is read-first, write-gated and lockout-aware: it never retries a failed login, gates every write behind two independent keys, restores power on every failure path, and refuses to act when the switch is in factory-reset mode.

Status: 0.1.0. The authenticated client, the typed read tools and the write / PoE power-cycle tools are implemented and covered by an offline test suite against synthetic fixtures. Live on-device verification (phase S4) is the last step before a tagged release; see docs/specs/.

Why

The Easy Smart line has no JSON API. Each page is HTML with an inline var NAME = VALUE; state block, and changes are made with *.cgi form posts over a cleartext HTTP login on port 80 — there is no TLS on the device. This server re-implements that protocol as a set of typed, safety-gated MCP tools, so an agent can answer "is the gate camera drawing power?" or "the hallway camera is frozen, power-cycle it" over the LAN.

Related MCP server: mcp-omada

Supported hardware

The switch's hardware revision and firmware are only readable after login, so for an unknown unit run tplink-easysmart-mcp check-auth --login once and compare.

Features

Thirteen tools, all prefixed switch_, all returning the same {success, data, error} envelope and never raising:

• System info — model, hardware revision, firmware, MAC, IP, netmask, gateway.

• Ports — per-port admin state, link, speed, flow control, LAG, name, protected flag.

• Statistics — tx/rx good/bad packet counters, with derived error_ports.

• PoE — budget totals and per-port state/priority/limit/class/W/mA/V/status, with derived fault_ports and unpowered_enabled_ports.

• VLANs — the 802.1Q table and per-port PVIDs (or NOT_SUPPORTED).

• Resolve port — preview how a name or number maps to a physical port.

• Writes (gated): switch_set_poe, switch_set_port, and switch_poe_cycle (power-cycle a PoE camera off → wait → on → confirm power).

Install

Requires Python 3.11+.

pip install git+https://github.com/ebenezer-isaac/tplink-easysmart-mcp
# or, from a clone:
pip install .

Register it with your MCP client (stdio transport) — for example in a Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "tplink-switch": {
      "command": "tplink-easysmart-mcp",
      "env": {
        "EASYSMART_HOST": "192.0.2.10",
        "EASYSMART_PASSWORD": "your-switch-password",
        "EASYSMART_PORT_MAP": "cam_hall=1;cam_gate=2"
      }
    }
  }
}

Leave EASYSMART_ALLOW_WRITES unset (the default) to run read-only. See the next section for every variable.

Configuration

Copy .env.example and fill it in, or pass the variables through your MCP client's env. The switch address, password and port map live only in that file — never in the repo.

VERIFY_TLS / TLS_FINGERPRINT_SHA256 are rejected if set — the device is HTTP-only, so they could do nothing but mislead.

Running

tplink-easysmart-mcp                      # serve over EASYSMART_MCP_TRANSPORT
tplink-easysmart-mcp --list-tools         # print the 13 tool names; no device I/O
tplink-easysmart-mcp check-auth           # probe only (one GET, no login)
tplink-easysmart-mcp check-auth --login   # exactly one login, confirm, then log out
tplink-easysmart-mcp breaker --show       # print the persistent breaker state
tplink-easysmart-mcp breaker --clear      # clear the breaker after fixing the cause

Safety model

This device makes safety the whole point of the project. See SECURITY.md for the full threat model.

• Cleartext login → LAN host only. The password crosses the wire in cleartext on every login. Run this server on the wired LAN host that reaches the switch — never across WiFi or a Tailscale/SSH hop. The HTTP transport binds to loopback; reach the MCP over Tailscale/SSH, but keep the switch traffic local.

• Writes are double-gated. A mutating tool acts only when EASYSMART_ALLOW_WRITES=true on the server and confirm_write=true on the call. Miss either and the tool returns a refusal before any network call.

• Dry-run. EASYSMART_DRY_RUN=true makes a write read the live page and return the exact bytes it would send, sending nothing.

• Read-modify-write + verify. Every write reads the current page, changes only the one field, re-sends the rest verbatim, then re-reads to confirm — so a PoE on/off never silently resets priority or limit (WRITE_VERIFY_FAILED if it did).

• Protected ports. EASYSMART_PROTECTED_PORTS (required when writes are on) names the uplink and the server's own port; no write or power-cycle touches them.

• Single-session eviction. The switch is effectively single-session: logging in evicts a human's web-UI session and vice versa. The server logs in lazily, re-logs in at most once per read, and logs out after every write.

• Restored-account / factory-reset refusal. In factory-reset mode a login POST would set the admin password. The server detects the "New Password / Confirm" page, refuses to POST, and trips the breaker.

• Lockout breaker + cooldown. A failed login (bad credentials, locked account, restored mode) trips a persistent breaker that blocks further logins until a human runs breaker --clear; session-busy / timeout responses set a cooldown instead. The login is never retried automatically.

• One cycle per port, crash-visible. Only one power-cycle runs per port at a time, reserved through a cross-process state file so a crashed cycle stays visible. Once the port is off, every failure path still tries to turn it back on and reports both outcomes; power is restored on every path.

• Exit codes (for check-auth / breaker in scripts): 0 success · 1 auth failed · 2 config error · 3 breaker open / cooldown / login disabled / state unavailable · 4 transport error.

Tools

A port argument is an int or a case-insensitive EASYSMART_PORT_MAP name (switch_resolve_port previews the mapping; resolution is type-stable, so 3 and "3" are always the same physical port).

Recipes

Power-cycle a wedged camera by name. With writes enabled and the camera in EASYSMART_PORT_MAP:

switch_poe_cycle(port_or_name="cam_hall", off_seconds=10, confirm_write=true)

It turns PoE off, waits, turns it back on, and polls until the camera draws power again — restoring power and reporting the outcome even if a step fails. Dry-run it first (EASYSMART_DRY_RUN=true) to see the exact off/on forms.

Check the PoE budget.

switch_get_poe()

Returns the system budget (limit / consumption / remaining) and every port's draw, plus fault_ports (overload/short/voltage/thermal) and unpowered_enabled_ports (PoE enabled but no power — often a dead or unplugged PD).

Limitations

• Live verification pending. The protocol is implemented from the MIT reference client and synthetic fixtures; the on-device S0 capture and S4 cycle test have not been run. Items a live unit must confirm are tagged # S0: confirm in switch/constants.py (the auto power-limit wire value, the per-port array padding, the disabled-PoE read value, whether Logout.htm ends the session, and whether the 802.1Q pages exist under these names).

• VLAN writes are not exposed. The VLAN read layout is inferred from sibling models; VLAN writes have two incompatible firmware shapes and are intentionally not implemented.

• Cable diagnostics are unknown. No reference client implements the cable-test page; it is not a tool.

• Hardware revision needs a login. It is only on SystemInfoRpm.htm.

Troubleshooting

• AUTH_FAILED / LOCKED_OUT and the breaker is now open. A login was rejected (errType 1/2). The server will not retry. Fix the credentials, then tplink-easysmart-mcp breaker --clear. Do not loop on login — the switch locks the admin account.

• LOGIN_NOT_ACCEPTED. The login POST returned errType 0 but the confirming GET came back as the login page (a known silent-ignore on cookie firmware). The credentials may be fine; a cooldown is recorded rather than tripping the breaker.

• SESSION_BUSY. Another process on your IP (usually a browser tab on the switch) already holds the session. Close it and retry.

• RESTORED_ACCOUNT_MODE. The switch is in factory-reset "set a new password" mode. Set the admin password in the web UI first; the server will not do it.

• AUTH_VARIANT_UNSUPPORTED. The firmware uses the encrypted login variant, which is not yet supported.

• OUTCOME_UNKNOWN. A write's connection was reset. The server re-reads rather than resending; check switch_get_poe / switch_get_ports for the real state.

• CYCLE_IN_PROGRESS that never clears. A previous cycle crashed and left a reservation. A marker older than its window is reported stale and overwritten; if it persists, remove the cycle marker under EASYSMART_STATE_DIR.

• errType meanings: 0 ok/silently-ignored · 1 bad credentials · 2 user blocked · 3/4 session slots full · 5 session timeout · 6 restored-account mode.

Prior art and credits

• vmakeev/hass_tplink_easy_smart (MIT, © 2022 Vladimir Makeev) — the request flow and the inline-variable / PoE / port parsing logic are ported from this Home Assistant integration (logic re-implemented, no files copied). See NOTICE.

• t0mer/SwitchDeck (Apache-2.0) — read for SG108E page/field names and connection-reset behaviour.

• pklaus/smrt — reference for the Easy Smart web protocol and page conventions.

Development

python -m venv .venv && .venv/Scripts/python.exe -m pip install -e ".[dev]"   # Windows
# or: python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
python scripts/gate.py   # ruff + pytest (coverage) + secret scan + stub scan + --list-tools

scripts/gate.py must print PASS before any commit. See CONTRIBUTING.md for the workflow, the breaker protocol, and the core-identity rule (core/ is canonical in vigi-nvr-mcp and copied verbatim). Protocol notes live in docs/protocol/easysmart-switch.md; the full specs and endpoint map are in docs/specs/.

License

MIT. See NOTICE for third-party attribution.