legacy-switch-mcp
This server is a read-only switch discovery, inspection, documentation, and backup toolset.
List configured switches and host IPv4 interfaces usable for discovery.
Discover switches via UDP broadcast/multicast on an interface, or probe a specific switch by IP.
Read raw switch web UI pages and get parsed state, including VLANs, ports, mirroring, trunks, and system details.
Get a consolidated overview of a switch in one login.
Save parsed state backups and list saved snapshots.
Generate a Markdown switch description for documentation/wiki use.
Download switch configuration files, and D-Link firmware images, to the state directory; list saved files without exposing contents.
It cannot make changes: no VLAN, port, trunk, mirror, password, IP, reboot, reset, restore, save, plan, or apply tools are exposed in this schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@legacy-switch-mcp show me the current VLANs and ports on usr-switch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 (seeLICENSE).
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.
Related MCP server: sos-microtik-mcp
Tools
Tool | What it does |
| configured switches; IPv4 interfaces on this host |
| UDP discovery (broadcast+multicast), or ask one switch by IP |
| parsed state: VLANs, ports, mirror (and D-Link system/trunk) |
| raw page data |
| save the parsed state; list saved states; markdown description for a wiki |
| download the configuration (both) / firmware (D-Link) file into the state directory, mode 0600; the content is never returned |
| maintenance plans (both vendors; reboot D-Link only). Applying needs the server started with |
| USRobotics changes (plan only) |
| D-Link changes (plan only) |
| apply a plan from this server session |
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 addressesPasswords 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-mcpKeeping 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:
Setup | Tools | Tokens per request (approx.) |
default: read + files + a set for each vendor in | 28 (both vendors) | 2,450 |
default + | 33 | 2,850 |
| 23 | 1,800 |
| 10 | 600 |
| ||
Maintenance plan tools are not registered at all unless the maintenance switch is on (or | ||
For day-to-day looking: |
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 onlye2e_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 unlessallow_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, USRobotics192.168.0.1, both with the passwordadmin(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 inpasswords.json(old one kept inpasswords.prev.json; apasswords.pending.jsonexists while a change is in flight) and never shown or logged. An IP change refuses unlessallow_ip_change=true, if the address answers a ping, or if it is outside the gateway's subnet, and updatesswitches.jsononly after logging in at the new address. Reboot, reset and restore drop every port, so they are refused whileprotected_portsexist unlessallow_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
Feature | State |
Discovery (both vendors) | proven on hardware |
Reads (both) | proven on hardware |
USRobotics writes: VLAN group, port, mirror | proven on hardware (round trips, switch left as found) |
USRobotics write: trunk | proven on hardware 2026-11-08 (ports 17+18, both idle; answers in ~11 s, so the write has a 45 s timeout) |
USRobotics write: system name/location/timeout | proven on hardware 2026-11-08 (location set and restored; the page also holds the IP settings, which are read back and re-sent unchanged, and did not change) |
D-Link writes: VLAN add/delete, PVID, port, mirror | proven on hardware 2026-11-08 (unused port 8, VLAN 999; every write verified by read-back and rolled back, switch left identical to its backup) |
D-Link writes: system name/location/timeout, save configuration | proven on hardware 2026-11-08 (location set and restored; save has no read-back) |
D-Link writes: trunks | proven on hardware 2026-11-08 (idle ports 6+7: trunking switched on, group created, then removed and trunking switched off; no ping loss on the other ports) |
The MCP tool layer (33 tools over stdio) | proven against a real D-Link with |
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=0toPortMirroring.cgigets 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)
Item | State |
Config download (USRobotics | proven on hardware 2026-11-08, read-only. The D-Link file contains the admin password in clear text: it is stored 0600 and never returned |
Firmware download (D-Link | proven on hardware 2026-11-08, read-only. The USRobotics web interface has no firmware page |
USRobotics system name/location/timeout | proven on hardware 2026-11-08 (location changed and restored; the IP settings were re-sent unchanged and did not change) |
Password change (both) | proven on hardware 2026-11-08 (run by the operator with |
IP change (both) | proven on hardware 2026-11-08: D-Link 198.51.100.3 -> .4 -> .3 and USRobotics 192.0.2.3 -> .9 -> .3 (shown here as documentation addresses), each verified by logging in at the new address; |
Reboot (D-Link; the USRobotics has no reboot page) | proven on hardware: back in about 7 s, ~2 s of ping loss behind it, uptime reset, saved password survived (save the configuration first: |
Factory reset + config restore, D-Link | proven on hardware: reset -> |
Factory reset, USRobotics | proven on hardware, but the recovery is different: after the reset, uploading the switch's own |
Config restore, USRobotics | the upload is accepted and the switch reboots (~30 s), but see above: do not rely on it to restore settings after a reset |
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
adminagain and the stored entry must say so beforeplan_passwordcan 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
Item | Why |
Firmware upgrade (D-Link | the upload protocol behind the button is unknown (the page only has buttons), and a bad image or a power cut during the write can brick the switch. |
The vendor utility's SOAP/UDP channel for writes ( | not captured; the web channel covers everything above. |
DHCP (instead of a static address), 802.1Q mode switch | no need so far; the D-Link |
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.
Available Tools
13 toolsbackup_configA
Download the configuration file to the state directory (mode 0600; it is a secret). Returns only id, size, checksum. Read-only.
Inputs: switch (required).
backup_firmwareB
Download the D-Link's running firmware image (~740 KB) to the state directory. Read-only; the USRobotics has none.
Inputs: switch (required).
backup_stateB
Save the parsed state to a JSON file under ~/.local/state/switch-mcp/backups. Read-only on the switch.
Inputs: switch (required).
describe_switchC
Markdown description of a switch's configuration for a wiki. Read-only.
Inputs: switch (required). Returns: result
discoverB
Broadcast/multicast discovery on one interface (e.g. vmbr0). Sends requests only; changes nothing.
Inputs: interface (required), wait_seconds. Returns: result
get_stateB
Parsed state: VLANs/groups, ports, mirror, trunks, system. Read-only.
Inputs: switch (required).
list_filesB
Saved configuration/firmware files (id, size, time; never content), newest first.
Inputs: switch. Returns: result
list_interfacesB
IPv4 interfaces on this host that discovery can use.
Inputs: no named parameters. Returns: result
list_snapshotsB
Saved state files (backups and the snapshot before every apply), newest first.
Inputs: switch. Returns: result
list_switchesA
Configured switches (name, address, vendor); edit ~/.config/switch-mcp/switches.json to add more.
Inputs: no named parameters.
overviewC
Everything useful in one login (USRobotics: its main pages; D-Link: the parsed state).
Inputs: switch (required).
probeA
Ask one switch by IP (works across subnets); returns its discovery reply or {"error": ...}.
Inputs: host (required).
read_pageB
One raw page of a switch's web UI. USRobotics: status, port, vlan, trunk, mirror, statistics, system, trap. D-Link: system, vlan, port, mirror, pvlan, mgmt_vlan, trunk. Read-only.
Inputs: page (required), switch (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
discover vs probe are clearly distinct (broadcast on an interface vs targeted IP query), but overview and get_state overlap significantly—overview for D-Link returns 'the parsed state' which is also get_state's stated purpose. Similarly list_snapshots and list_files both enumerate saved files, requiring careful reading to distinguish.
Most tools follow a verb_noun pattern (list_switches, get_state, backup_config, describe_switch), but discover, probe, and overview are bare verbs/nouns, creating minor inconsistency. The convention is still readable and predictable overall.
13 tools is well-scoped for a switch management server covering discovery, inspection, and backup. Each tool appears to earn its place in the workflow without excessive granularity.
The surface is rich for read-only inspection and backup (discovery, state parsing, config/firmware backup, snapshots, wiki descriptions), but lacks any mutation or apply operations despite list_snapshots referencing 'the snapshot before every apply.' Agents cannot change switch configuration, a notable gap for a management server.
Maintenance
Related MCP Connectors
EOL dates, risk scores, CISA KEV exposure, SBOM audits and edge-device EOS for 700+ products.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Detects database migration table locks, terraform cost leaks, and OWASP API flaws.
Cloud cost, inventory and governance on AWS/Azure/GCP. Read-only by default, optional scoped writes
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI clients to safely read and configure Zyxel GS1900 smart-managed switches via typed MCP tools with guardrails like dry-run, auto-backup, and protected ports.261MIT
- AlicenseAqualityCmaintenanceEnables technicians to discover, audit, and configure MikroTik RouterOS routers over SSH, with dry-run change plans, automatic rollback, and local handling of credentials and keys.22MIT
- AlicenseAqualityBmaintenanceLets an MCP client read port, statistics, VLAN and PoE status from TP-Link Easy Smart switches and, when explicitly gated, power-cycle a wedged PoE camera over the LAN without opening the switch's web UI. It talks the switch's HTML/cgi protocol directly, with double-gated writes, dry-run, protected ports, and lockout-aware failure handling.13MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read and change MikroTik SwOS / SwOS Lite switches live over their web API, with field maps learned from each switch, safe dry-run and confirm writes, and .swb backup decoding, diffing, and restore.MIT