legacy-switch-mcp

Use at your own risk. This tool can change VLANs, reboot switches and factory-reset them, and a bad change can cut you off from the switch. It has been proven on hardware on exactly two models (USRobotics 7724, D-Link DGS-1100-08) and is fake-switch tested only elsewhere. Read the plan before applying it, list your uplinks in protected_ports, and keep the maintenance switch off unless you need it. Provided as is, without warranty (see LICENSE).

An MCP server for two old "smart" switch families that no other MCP covers: the USRobotics 7724 (24-port gigabit, port-based VLANs) and the D-Link DGS-1100 EasySmart series (802.1Q). Both are Cameo-built and share a UDP discovery protocol (see docs/PROTOCOL.md).

It reads state and makes changes the careful way: plan, then apply. A plan writes nothing; it shows the exact differences and the risks (for VLANs: which connected ports would stop reaching each other, which ports leave the management VLAN). Applying needs the plan id and confirm=true, re-reads the switch and refuses if it changed, saves a snapshot, writes, reads back to verify, and returns a rollback plan.

Install

No clone needed (needs uv). First create ~/.config/switch-mcp/switches.json and a password for each switch (see Setup below), then add the server to your MCP client:

claude mcp add switch -- uvx legacy-switch-mcp                                    # Claude Code
claude mcp add switch --env SWITCH_MCP_TOOLSETS=read -- uvx legacy-switch-mcp     # look-only (fewest tokens)

Claude Desktop, Cursor and other clients take the same command in their JSON config:

{"mcpServers": {"switch": {"command": "uvx", "args": ["legacy-switch-mcp"], "env": {"SWITCH_MCP_TOOLSETS": "read"}}}}

The package is on PyPI and in the official MCP Registry as io.github.Nebulous-Ideas/legacy-switch-mcp. To run unreleased code, use uvx --from git+https://github.com/Nebulous-Ideas/legacy-switch-mcp legacy-switch-mcp.

Tools

Setup

uv sync --extra dev && uv run pytest
mkdir -p ~/.config/switch-mcp && cp switches.example.json ~/.config/switch-mcp/switches.json   # then edit the addresses

Passwords are never tool arguments and are never returned. Provide each as SWITCH_MCP_PASSWORD_<NAME> (name upper-cased, - becomes _) or in ~/.config/switch-mcp/passwords.json ({"usr-switch": "..."}, mode 0600; a looser mode is refused).

Factory-default passwords (so a reset switch is usable): both vendors document admin as the default (USRobotics quick-install guide; D-Link EasySmart manuals, which also give 10.90.90.90 as the default D-Link address and 192.168.0.1 for the USRobotics). Change it after a reset. This repository contains no other credentials; tests use a throwaway pw.

Register with Claude Code only for switch work (every MCP server adds its tool descriptions to every request of the session):

claude mcp add switch -- uv run --project /path/to/legacy-switch-mcp legacy-switch-mcp

Keeping the session cost small

Only the tools that can be used are registered. Measured with all 33 tools registered the schema text was about 4,350 tokens; now:

Testing

uv sync --extra dev && uv run pytest            # 118 tests against the fake switches; no hardware needed
uv run python scripts/e2e_check.py <dlink-switch> <trunk-group> <port> <port>   # real MCP stdio check against a D-Link, on IDLE ports only

e2e_check.py starts the server as a client would, round-trips a system-location change and a trunk on the two idle ports you name (each rolled back), downloads a config, and checks that a reboot plan is refused while maintenance is off. Run it only against a switch where those ports have no link; it leaves the switch as it found it. Hardware-only checks (outages, factory reset, password) are in scripts/maint.py, scripts/rotate_password.py and scripts/recover_after_reset.py; see docs/ADDING-SWITCHES.md for the proof sequence.

Safety

See also SECURITY.md (threat model: plain-HTTP switches on a trusted management network; how to report a problem; supply-chain measures).

• Protected ports: list uplinks in switches.json ("protected_ports": [24]); plans that touch them are refused unless allow_protected=true.
• Rollback survives failure: the rollback plan is written to disk before any write, so if the switch stops answering mid-change it can still be applied from a new session.
• Where a switch comes back. After a factory reset (or if you lose track of a changed address) the switch returns to its vendor default: D-Link 10.90.90.90, USRobotics 192.168.0.1, both with the password admin (both proven on hardware). To reach it, put a host on the same layer-2 segment in the same subnet. discover(interface) finds switches by MAC on the local segment even when their address is not the one you expect, so you can search before you guess. The tool only works on layer 2: it cannot reach a switch through a router.
• Back up before the first write to a switch you cannot reach another way (backup_config, backup_state). A change that cuts the management path (a wrong address, VLAN or uplink) cannot be undone over the network; the way back is the default address above or a factory reset.
• Audit log: every plan, refusal and apply is appended to ~/.local/state/switch-mcp/audit.jsonl (no credentials).
• Maintenance is off by default. Password, IP address, reboot, factory reset and config restore plan normally but refuse to apply unless the server was started with SWITCH_MCP_ENABLE_MAINTENANCE=1 (claude mcp add switch --env SWITCH_MCP_ENABLE_MAINTENANCE=1 -- uv run ...). The low-level writers refuse too. Passwords are generated by the server, verified by logging in, stored in passwords.json (old one kept in passwords.prev.json; a passwords.pending.json exists while a change is in flight) and never shown or logged. An IP change refuses unless allow_ip_change=true, if the address answers a ping, or if it is outside the gateway's subnet, and updates switches.json only after logging in at the new address. Reboot, reset and restore drop every port, so they are refused while protected_ports exist unless allow_protected=true; a factory reset first saves the parsed state and the configuration file; a restore only accepts a file this server saved for the same switch (checksum checked).
• Only ten D-Link CGIs (VLAN add/delete, PVID, port, mirror, system name/location/timeout, save, three trunk CGIs) and five USRobotics forms (VLAN group, port, mirror, trunk, system name/location/timeout) can ever be posted in normal operation. Behind the maintenance switch: five more D-Link CGIs (password, IP, reboot, reset, restore) and four USRobotics forms (password, system with IP, reset, restore); two D-Link CGIs only download a file. Firmware upgrade, 802.1Q-mode changes and anything else cannot be posted.
• Plans live in server memory for 10 minutes; snapshots go to ~/.local/state/switch-mcp/.
• One web session at a time (these switches evict a second login), always logged out. If a human has the web page open, close it first.
• The switches apply changes live; they may not keep them across a power loss unless saved from their own web page.

Status

Found on hardware (the fake switches could not have told us)

• USRobotics login check was wrong: the reply to a wrong password has no login form (it only appears on the next page), so every password looked valid. Logins now fetch a real page and require it not to be the login form. This also made "verify the new password by logging in" meaningful for the USRobotics.
• D-Link mirror disable: posting only cEn=0 to PortMirroring.cgi gets no answer at all and applies nothing (ReadTimeout, repeatable). The switch answers in 0.1 s when the form also carries the current sniffer port, mode and source ports. Fixed; the fake now hangs the same way so a regression fails a test.
• USRobotics trunk: the write applies but takes about 11.4 s to answer, longer than the 10 s default timeout; it was reported as "lost contact" although it had worked. Trunk writes now wait up to 45 s.

Maintenance operations (behind SWITCH_MCP_ENABLE_MAINTENANCE=1)

Operational notes from the outage tests

• In the test setup the D-Link carried only a redundant second link and the USRobotics carried the main LAN plus the first link: a D-Link reboot/restore/reset cost a few seconds of ping loss on that link, a USRobotics reset/restore takes the whole LAN down for about a minute. Do one switch at a time.
• After a USRobotics factory reset its password is admin again and the stored entry must say so before plan_password can rotate it (the recovery sets it; rotate again afterwards).
• Reaching a reset switch at its factory address needs a temporary host route on the machine running the tools (ip addr add <x>/32 + ip route add <default>/32 dev <bridge>), not a /8 or /24 alias that would capture other traffic.

Not implemented

See docs/ADDING-SWITCHES.md for how to add another switch, another model or firmware, or a new vendor.

Related projects (other gear with no vendor API)

• tplink-easysmart-mcp: TP-Link Easy Smart switches over their web CGI, with dry-run, protected ports and lockout-aware failures.
• A second TP-Link Easy Smart server (tplink-easy-smart-switch-mcp, by qwe7002-ai) and a Netgear XS512EM server (netgear-xs512em, by supere989); find them by name on GitHub.
• NetContext-MCP: SSH to older CLI switches (Cisco, Aruba) with legacy algorithms.

The gated-write pattern here (dry run, risk checks, session-eviction caveat) follows the same approach; ideas flow both ways.

See docs/PROTOCOL.md for the wire formats and the page/CGI map and docs/IDEAS.md for what was borrowed from the projects above and a sketch of a multi-vendor umbrella (an idea only).

A Nebulous Ideas project, built by the Nebulous Collective: the people and agents who work on it.