WhiteOmadaMcp
Provides tools for interacting with TP-Link Omada controllers through both the Open API v1 and GUI API v2. It enables read-only diagnostics and guarded configuration changes across switches, ports, VLANs, PoE, access-point radios, SSIDs, clients, topology, and logs, with dry-run previews, read-back verification, and secret redaction.
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., "@WhiteOmadaMcp Why does my phone keep dropping Wi-Fi?"
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.
At a glance
Related MCP server: AI Network Troubleshooting MCP Server
Tech stack
Area | Used for |
Runtime | Node.js 18+, standard library only; MCP over stdio (JSON-RPC); every tool carries readOnly, destructive and idempotent annotations |
Controller access | Open API v1 (client credentials) and the GUI's v2 API (session); the v2 endpoint map was derived from the controller's own GUI bundles and probed live |
Safety | Separate read and write credential sets, a server-side write gate, dry run by default, read-back diff, recursive secret redaction, SSRF and path-traversal guards |
Diagnostics | Interference from the access points' own radio counters, DFS/radar audit, per-client association history, channel-utilisation swing, client-survival check, security audit |
Quality | 54 offline tests with node:test, 12 read-only live tests that assert a write is refused; long-running RF and DFS collectors for unattended evidence |
What you can ask
Connect it to an MCP client (Claude Desktop, Claude Code or any other) and ask in plain language. The model chooses the tools; you get an answer with the evidence behind it.
You ask | Tools the model uses | What comes back |
"Why does my phone keep dropping Wi-Fi?" |
| Every association over N days by AP, channel and band, disconnects per day, and the roaming and SSID settings known to cause drops |
"Is something interfering with my Wi-Fi?" |
| Non-WiFi interference measured by the access points themselves, kept apart from ordinary congestion |
"Did radar push my 5 GHz off its channel?" |
| Which radios are on DFS channels, a live watch for channel changes, AP uptime and a log sweep |
"Which switch port is the TV on, and on which VLAN?" |
| The device, port, VLAN, link speed and PoE state |
"Is my network configured safely?" |
| Ranked findings, each with the exact fix and its blast radius |
"Turn off 802.11r on the home SSID." |
| A dry run showing the exact request; with write access, the change applied, read back and verified |
On the reference network, the client-history and SSID checks traced clients dropping while roaming between access points to 802.11r. Turning it off cut client disconnects from 20.9 to 8.0 an hour.
Why both APIs
Neither API alone is enough on a modern controller, and each one fails in a way the other covers:
Open API (v1) | GUI API (v2) | |
Documented and stable | ✅ | ❌ reverse-engineered |
Event and audit logs | ✅ | ❌ returns 0 rows on 6.2+ |
Switch ports, STP, PoE, VLAN profiles | ❌ | ✅ |
AP radio writes | ❌ silently reverts | ✅ |
SSID rate control | ✅ | ✅ |
Measured on a 6.2.14.11 controller: the v1 log endpoint returned 88,522 events over 30 days where v2 returned zero. Meanwhile v1 accepts an AP radio write, reports success, and the controller quietly keeps the old value.
So every operation declares which transports can serve it, tries the preferred one, falls back, and reports which API actually answered. That last part matters: a controller upgrade that moves an operation between the two APIs is otherwise invisible, and that exact move is what broke logs on 6.2.
Install
git clone https://github.com/ricardo-david-francisco/WhiteOmadaMcp-public.git
cd WhiteOmadaMcp-public
cp .omada-secrets.env.EXAMPLE .omada-secrets.env
# edit .omada-secrets.envThen point your MCP client at omada-v2-mcp.js — see claude_desktop_config.EXAMPLE.json.
Run it read-only, and mean it
The recommended setup is two instances:
omada → read credentials only, OMADA_ALLOW_WRITES=false
omada-write → write credentials, OMADA_ALLOW_WRITES=trueWrites require both write credentials and the explicit opt-in. Neither alone is enough, and the default is read-only, so a fresh clone cannot change your network.
In read-only mode a write tool does not fail silently. It returns the exact request it would have sent:
🔒 REFUSED — this server is READ-ONLY (no write credentials configured).
SSID <your-iot-ssid> 2g rate control -> {"rate2gCtrlEnable":true,"lowerDensity2g":12,...}
transport : v2
current : {"rate2gCtrlEnable":false,...}
The exact request that was NOT sent:
PATCH /sites/<siteId>/setting/wlans/<groupId>/ssids/<ssidId>
{ "name": "...", "pskSetting": { "securityKey": "(redacted)" }, ... }v2_mode tells you which mode you are in and why.
Safety rules baked in
Every write is read back and diffed. A controller that returns
Successand changes nothing is reported asREVERTED, not as success. Omada does this on several endpoints.Writes default to
dryRun: true.Secrets are redacted recursively before anything is returned. Audit-log diffs embed cleartext Wi-Fi passphrases; reading a log should not be a way to harvest every PSK.
Human units at the boundary. You say
channel: 100andwidthMHz: 40; the server handles the fact that Omada wants a 1-based index intochannelRangeand(MHz/20)+1.Destructive changes preview their casualties. Setting an RSSI kick threshold or a minimum data rate lists the clients that would be affected before sending.
No tool can create, enable or extend an account.
What it can tell you
Beyond configuration, the diagnostic tools exist because vague answers are worse than none:
v2_radar_audit— settles a DFS argument with evidence: which radios are actually on DFS channels, a live watch for an unrequested channel change, AP uptime, and a per-AP log sweep. States plainly what it cannot prove.v2_client_history— every association a device made over N days, by AP and channel, so you can tell a band-steering problem from a roaming problem from a device that simply drops.v2_channel_util— samples utilisation over time and reports the swing, because 2.4 GHz can move 30–55 points on its own and a single reading proves nothing.v2_client_survival— snapshot, wait, re-check, and name anything that disappeared. This is how you catch a setting that silently evicted an IoT device instead of just reading "Success".v2_security_audit— flags PMF Mandatory (value1) on WPA2-PSK, and WPA2/WPA3 transition mode. Omada's PMF enum is1 = Mandatory, 2 = Capable, 3 = Disabled;1is the strictest value, not the weakest. It does not tell you to enable 802.11r — on the reference site that was the cause of the roaming disconnections, not the cure.
Errors, decoded
errorCode | Meaning |
| Bad or missing parameters — the endpoint exists. Usually a required sibling field. |
| Path does not exist on this build. |
| Licence gate. |
| Your account's role lacks that page. |
| Feature needs hardware you do not have. |
| Login refused: 2FA is enabled. The v2 login API cannot complete it. |
| Gateway not connected. |
Testing
node --test test/unit.test.js # no controller needed
OMADA_LIVE_TEST=1 node --test test/live.test.js # read-only, against a real controllerThe live suite forces OMADA_ALLOW_WRITES=false and asserts a write is refused, so it cannot
change your network even if the gate were broken.
The development repository's CI runs unit tests on Node 18/20/22/24, CodeQL, gitleaks, an MCP-contract check that every tool is annotated, and a privacy scan that fails the build on a committed private IP, MAC address or controller GUID.
Contributing
Default branch is main. Two things will get a PR rejected regardless of merit:
A new runtime dependency. CI enforces zero.
A write path that does not read back and diff. "The controller said Success" is not evidence that anything changed.
Licence
MIT — see LICENSE.
Not affiliated with TP-Link. The v2 API is undocumented and may change without notice; that is precisely why every write here verifies itself.
Available Tools
59 toolsoa_getARead-onlyIdempotent
GET any Open API (v1) path, relative to /openapi/v1/{omadacId}. The v1 API is the ONLY one that returns event and audit logs on controller 6.2+ (measured: 88,522 events via v1, 0 via v2).
Inputs: path (required), query.
v2_alertsBRead-onlyIdempotent
Site ALERT log (the subset of events flagged as alerts), with archived/unarchived filter, level, module, time window and search.
Inputs: hours, level, limit, module, +3 more.
v2_ap_radiosARead-onlyIdempotent
Per-AP everything in REAL UNITS: channel/width/power per band, allowed channels, RSSI kick, load balance, WMM, OFDMA, mesh, management SSID, multicast VLAN, wired uplink rate, per-AP SSID enablement. Omit apMac for all APs.
Inputs: apMac, siteId.
v2_audit_logsARead-onlyIdempotent
AUDIT log: who changed what, from which IP, with old and new values. This is the accountability trail — separate from events.
Inputs: hours, limit, siteId.
v2_channel_utilARead-onlyIdempotent
Sample 2.4/5 GHz channel utilisation over time and report mean/median/min/max per channel. Use BEFORE and AFTER any RF change — this band swings 30-55 points on its own, so a single reading proves nothing and a short baseline will let you claim any result you like.
Inputs: siteId, samples, intervalSec.
v2_client_historyARead-onlyIdempotent
Every association a given client made over N days: which AP, which channel, which band, and how often it disconnected. This is how you tell a band-steering problem from a roaming problem from a device that simply drops. Uses the v1 log API, which is the only one that returns events on 6.2+.
Inputs: mac (required), days, siteId.
v2_clientsARead-onlyIdempotent
Known-client list: name, MAC, vendor, wired/wireless, VLAN, traffic totals, last seen, blocked state. NOTE this build's endpoint carries NO RSSI, SSID, AP or rate data — the tool says so rather than inventing it. Pass a mac to get that one client's full detail (vendor, OS, device type, IP settings, rate limit).
Inputs: mac, limit, siteId.
v2_client_survivalARead-onlyIdempotent
Snapshot every wireless client, wait, then re-check and name anything that disappeared. Run this after any RF or SSID change — it is how you catch a setting that silently evicted an IoT device instead of just reading "Success".
Inputs: band, siteId, waitSec.
v2_controller_settingsARead-onlyIdempotent
Controller-level configuration: name, timezone, DST, controller NTP, HTTP/HTTPS ports, certificate, mail server, logging levels, built-in RADIUS, device access management, data retention, uptime and version. Flags controller NTP off and plaintext management.
Inputs: no named parameters.
v2_delete_userADestructive
DELETE a controller account. Deliberately the only account operation this server has: deleting removes access, it cannot grant it, so no credential in this config can mint admin. Refuses the account you are logged in as and refuses Owner/root accounts. Requires confirm:true. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: username (required), dryRun, confirm.
v2_dfs_checkARead-onlyIdempotent
DFS/radar evidence. Compares each 5 GHz radio's CONFIGURED channel against the channel it is ACTUALLY operating on. A radar detection forces a 30-minute vacate onto a different channel, so configured != actual is a radar event caught in the act. Also flags which radios are on DFS channels at all, and whether any sits in the 5600-5650 MHz weather-radar sub-band.
Inputs: siteId.
v2_diagnosticsARead-onlyIdempotent
The 6.2 diagnostic surface in one call: client distribution per band / per SSID / per AP, RSSI histogram, association failures (timeout, WPA failure, blocked), association-time buckets, client activity over time, longest-uptime devices, top applications, per-channel utilisation, per-AP interference, and PoE budget. This is the tool for "is the wireless actually healthy", as opposed to "is it configured correctly".
Inputs: siteId.
v2_endpointsARead-onlyIdempotent
The verified v2 endpoint map for this build (6.2.14.11), derived from the controller's own GUI bundles and probed live — including what is NOT available and why. Read this before guessing a path.
Inputs: filter.
v2_eventsBRead-onlyIdempotent
Site EVENT log with real filters: level (Error/Warning/Information), module (Operation/System/Device/Client), time window in hours, free-text search, paging. Diagnoses an empty result rather than reporting silence as health.
Inputs: hours, level, limit, module, +2 more.
v2_getARead-onlyIdempotent
GET any v2 path (relative to /api/v2). Use for anything the typed tools do not cover. Returns errorCode triage on failure.
Inputs: path (required), query.
v2_health_auditARead-onlyIdempotent
One-shot audit across site settings, controller settings, services, switches, ports, VLAN profiles, radios, SSIDs, VLANs and logs. Returns a ranked list of misconfigurations, each with the exact tool call that fixes it and its blast radius.
Inputs: siteId.
v2_interference_auditARead-onlyIdempotent
REAL interference detection, not inference. Uses the AP's own radio counters — interUtil (airtime lost to NON-WiFi emitters), busyUtil, txUtil/rxUtil, and rx/tx retry and drop deltas — sampled over time. Separates "the band is busy with WiFi" from "something non-WiFi is transmitting", which is the distinction that makes every other interference claim a guess. Optionally correlates against live aircraft overhead (opt-in, sends an approximate location to a public flight API).
Inputs: lat, lon, band, siteId, +3 more.
v2_lan_networksBRead-onlyIdempotent
Every VLAN: name, tag, subnet, DHCP scope, IGMP/MLD snooping, DHCP guard, purpose. Flags networks with snooping off.
Inputs: siteId.
v2_log_diagnoseARead-onlyIdempotent
Why is the log empty? Runs the full evidence chain in one call: every log surface (site/controller events, alerts, audit), the stored-log counter vs its cap, retention policy, the notification catalogues that decide what gets recorded at all, and remote syslog state. Use this before concluding a quiet network — an empty log and a healthy network look identical.
Inputs: siteId.
v2_log_settingsBRead-onlyIdempotent
Everything that governs whether logs exist at all: site alert switch, remote syslog target, controller log retention policy, controller logging levels, webhook targets, and the current stored-log count against the cap. Explains an empty log rather than leaving it mysterious.
Inputs: siteId.
v2_modeARead-onlyIdempotent
What this server is allowed to do: read-only vs write-enabled, which credential sets are loaded (never the values), which API is preferred, and the v1/v2 reachability of both transports. Call this to explain why a write was refused.
Inputs: no named parameters.
v2_notificationsBRead-onlyIdempotent
The notification catalogue — which events are recorded, which raise alerts, and which send mail or webhook. This is the real alerting control; the alert.enable field in site settings is NOT writable and does not correspond to this page. Reads controller scope and site scope separately, because they are different catalogues.
Inputs: scope, siteId, confirm, restoreDefaults.
v2_past_connectionsBRead-onlyIdempotent
Historical client sessions: MAC, SSID/network, AP, duration, traffic, disconnect reason. Use for "why did this device drop".
Inputs: hours, limit, siteId.
v2_port_statsARead-onlyIdempotent
Live per-port counters: link state, tx/rx bytes and packets, ERRORS and DROPS, plus PoE draw in watts per port and total budget. This is the tool for "is a cable or a device misbehaving".
Inputs: siteId, switchMac.
v2_radar_auditARead-onlyIdempotent
Settle a DFS argument with evidence rather than opinion. Reports which radios are actually on DFS channels, watches them live for an unrequested channel change, checks AP uptime (a radar hit cannot happen without one or the other), and sweeps the v1 event log per-AP for radar entries. States plainly what it can and cannot prove.
Inputs: days, siteId, watchMinutes.
v2_rf_healthBRead-onlyIdempotent
RF diagnostics without touching anything: per-channel AP/client counts and channel utilisation on both bands, per-AP interference, client RSSI distribution, and the controller's own wireless experience index history. The closest thing this build has to a wireless test.
Inputs: siteId.
v2_rf_planningARead-onlyIdempotent
AI RF Planning — the controller's own channel/width/power optimiser. Reads the current plan settings, the run history with before/after experience index, and the status of the last run. Can trigger a new run with run:true. ⚠ A run re-plans channels across every AP and applies them, overriding any manual channel choice.
Inputs: run, siteId, confirm.
v2_rogue_apsARead-onlyIdempotent
Neighbouring/rogue APs seen by your own APs — SSID, BSSID, channel, signal, security. Empty until a scan has run.
Inputs: siteId.
v2_security_auditARead-onlyIdempotent
Security posture of every SSID in one table: WPA version, PMF (802.11w) mode, 802.11r, guest isolation, band, VLAN, broadcast. Flags the combinations that are known to destabilise clients — notably PMF Mandatory (value 1) on WPA2-PSK, and WPA2/WPA3 transition mode, which is defeated by a documented downgrade attack and gives WPA2 security with WPA3 compatibility problems.
Inputs: siteId.
v2_servicesBRead-onlyIdempotent
Every site service in one call: SNMP, SSH, mDNS, UPnP, IPTV/IGMP proxy, DHCP reservations, PoE schedules, reboot schedules, wireless MAC filter, 802.1X, MAC authentication, RADIUS profiles, rate-limit profiles, time ranges and IP/MAC groups. Flags insecure or unset services.
Inputs: siteId.
v2_set_ap_load_balanceBIdempotent
Fix or set per-radio load balancing. Guards the maxClients:1 landmine — refuses maxClients under 5 unless force:true. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: band (required), apMac (required), force, dryRun, +3 more.
v2_set_ap_mgmt_ssidADestructive
⚠ MEASURED NOT TO WORK on 6.2.14.11: mgtSsidSetting is read-only. The write returns success and the value reverts on read-back, the field appears in none of the 381 GUI modules, and no site-level control exists. Kept only so the attempt is recorded honestly rather than repeated — the tool will report REVERTED. Settle it with a phone scan instead. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: apMac, allAps, dryRun, enable, +2 more.
v2_set_ap_radioAIdempotent
Set AP channel / width / tx power in REAL UNITS (channel 100, widthMHz 40). Warns on DFS and the 5600-5650 MHz weather-radar band. Read-back verified. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: band (required), apMac (required), dryRun, siteId, +3 more.
v2_set_ap_rssi_kickAIdempotent
Set the RSSI threshold that disassociates a client clinging to a weak AP — the fix for sticky clients that sit at -80 dBm while a -55 dBm AP is in the same room. TP-Link: "if you did not set it, that is why you don't switch." Gentler than nonStickRoaming: it does not emit the MBO/OCE "cannot handle new STA" frames that feed Android's BSSID blocklist. ⚠ Set it BELOW the weakest signal you still want to keep, or you will disconnect distant devices you rely on. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: band (required), apMac, dryRun, enable, +2 more.
v2_set_ap_ssidAIdempotent
Enable or disable one SSID on ONE access point. This is the only real on/off switch an SSID has — there is no global enable field; on-air state lives per-AP in ssidOverrides[].ssidEnable. Use it to keep an SSID in one room only, or to cut beacon overhead on a busy band without changing coverage anywhere. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: enable (required), ssidName (required), apMac, apName, +2 more.
v2_set_lan_igmpAIdempotent
Enable/disable IGMP and MLD snooping on a VLAN. ⚠ Without an IGMP querier on that VLAN, snooping STOPS multicast instead of optimising it — test TVs and speakers immediately after enabling. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: networkName (required), dryRun, siteId, mldSnooping, +1 more.
v2_set_portAIdempotent
Set one switch port: loopback detection, STP on/off, STP edge-port and BPDU/root guard, storm-control thresholds, port isolation, PoE, enable/disable. ⚠ NEVER enable loopback detection on a switch-to-switch trunk — an edge loop could then shut the uplink and partition the network. The tool refuses trunk ports unless force:true. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: port (required), switchMac (required), poe, stp, +13 more.
v2_set_port_profileAIdempotent
Bind a switch port to a VLAN port profile — the real fix for "every port permits every VLAN". Refuses to change an inter-switch trunk unless force:true, because a wrong profile there partitions the network. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: port (required), switchMac (required), profileName (required), force, +2 more.
v2_set_port_pvidAIdempotent
Set a switch port's PVID — the VLAN an UNTAGGED frame lands on. This is what decides where a laptop plugged straight into the port ends up, and it is what makes a rescue/console port actually work without configuring the laptop. The tagged VLAN list is preserved unless you replace it. Refuses inter-switch trunks unless force:true. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: port (required), switchMac (required), pvidNetworkName (required), force, +3 more.
v2_set_ports_bulkAIdempotent
Apply one change to many ports at once, with the same trunk guard as v2_set_port. Select ports explicitly, or by selector: "access" (all non-trunk), "dead" (link down, non-trunk — zero blast radius), "all". Use this with edgePort:true before enabling STP on a switch: it is the step that turns a 30-second convergence outage into no outage at all on the access ports. Each port is written and verified individually. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: switchMac (required), stp, force, ports, +13 more.
v2_set_serviceAIdempotent
Toggle site services: SNMP v1/v2c/v3, SSH access, mDNS repeater, UPnP. Each is read back and diffed. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: ssh, mdns, upnp, dryRun, +4 more.
v2_set_site_featureBIdempotent
Toggle site-wide features: airtime fairness per band, alert logging (the audit trail), remote syslog target, LED, LLDP, auto-upgrade, band steering. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: dryRun, siteId, ledEnable, lldpEnable, +11 more.
v2_set_site_roamingAIdempotent
Set site roaming: fastRoaming (802.11r/k), aiRoaming, nonStickRoaming, pingPongSuppression, forceDisassociation. NOTE nonStickRoaming and forceDisassociation send MBO/OCE "cannot handle new STA", which feeds the Android BSSID blocklist and produces the "phone thinks it is banned" symptom. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: dryRun, siteId, aiRoaming, fastRoaming, +4 more.
v2_set_ssidAIdempotent
Change one SSID: enable/disable, broadcast, 802.11r fast roaming, PMF, guest isolation, prohibitWifiShare (the TTL clamp that breaks VMs and hotspots), VLAN and rate-limit profile. Read-back verified. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: ssidName (required), band, dryRun, enable, +8 more.
v2_set_ssid_rate_controlAIdempotent
802.11 rate control per SSID: disable CCK (kills 1/2/5.5/11 Mbps and the ERP-protection penalty), set the minimum data rate, choose whether beacons stay at 1 Mbps, and whether clients are FORCED to the minimum. Field schema verified against a live 6.2.14.11 controller. Warns about clients that would fall below the new floor before sending. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: ssidName (required), band, dryRun, enable, +6 more.
v2_set_switch_stpAIdempotent
Enable/disable STP on a switch and set bridge priority and timers (lower priority wins; 4096 forces root). ⚠ Enabling STP triggers ~30 s of listening/learning — ports carrying APs or cameras WILL drop. Do it when the network is quiet. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: switchMac (required), mode, dryRun, siteId, +2 more.
v2_site_settingsBRead-onlyIdempotent
FULL site settings decoded: roaming (fast/AI/non-stick/ping-pong/force-disassoc), band steering, airtime fairness, mesh, beacon+DTIM+RTS, LED, LLDP, NTP, alerts, remote syslog, auto-upgrade. Flags risky values.
Inputs: siteId, showSecrets.
v2_speedtestAIdempotent
Run the controller WAN speed test and poll for the result. NOTE: verified unsupported on this build (-1600) because the site has no Omada gateway — the tool says so explicitly instead of hanging. Kept for the day an ER-series router is adopted. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: siteId, waitSeconds.
v2_ssid_broadcastCRead-onlyIdempotent
Which APs broadcast which SSID, and change it per-AP. IMPORTANT SEMANTICS (verified): ssidOverrides[].ssidEnable is what decides whether an SSID is on the air on that AP; the sibling enable flag governs per-AP name/PSK/VLAN overrides and does NOT gate broadcast. Use this to keep an SSID on one AP only.
Inputs: apName, dryRun, siteId, ssidName, +1 more.
v2_ssidsARead-onlyIdempotent
Full config of every SSID: band, VLAN, security/PMF, 802.11r, guest isolation, prohibitWifiShare (the TTL clamp), rate control, MAC filter, schedule, multicast/broadcast handling. Passphrases redacted unless showSecrets.
Inputs: siteId, showSecrets.
v2_statusARead-onlyIdempotent
Login check: controller version, account, role, and hours left on a temporary account. Call this first.
Inputs: no named parameters.
v2_switchesCRead-onlyIdempotent
Switch-level state: model, firmware, uptime, CPU/mem, STP mode + bridge priority + timers, device-level loopback detection, jumbo frames, SNMP, LAGs, LLDP uplink/downlink neighbours. Flags STP-disabled switches.
Inputs: siteId.
v2_switch_portsARead-onlyIdempotent
Every port on every switch (or one switch), decoded with VLAN NAMES: link/speed, PVID, tagged/untagged, VLAN profile + profileOverride + profileVlanOverride, PoE, STP, loopback detection, storm control, isolation. Emits warnings for STP-off / loopback-off / all-VLAN / dead ports, and marks inter-switch trunks.
Inputs: siteId, switchMac.
v2_switch_statsBRead-onlyIdempotent
Per-switch statistics view: per-port operation, speeds, PoE and traffic totals as the Statistics page shows them.
Inputs: switchMac (required), siteId.
v2_topologyARead-onlyIdempotent
Physical topology: every node, what it is connected to, on which port, at what speed. Use this to confirm which ports are inter-switch trunks before touching loopback detection.
Inputs: siteId.
v2_usersARead-onlyIdempotent
Controller accounts: role, type, 2FA, temporary-validity window and hours left. This server can DELETE an account but can never create, extend or enable one.
Inputs: no named parameters.
v2_vlan_profilesBRead-onlyIdempotent
Switch VLAN port profiles (the "All"/"Disable"/custom profiles) fully decoded with VLAN names, plus which profile each switch port currently uses. This is what actually enforces per-port VLAN membership.
Inputs: siteId.
v2_wanBRead-onlyIdempotent
WAN/internet view: WAN network config, number of WAN ports, per-port state and IP. On a controller with no Omada gateway this reports what is and is not manageable.
Inputs: siteId.
v2_writeCIdempotent
Escape hatch: any PATCH/POST/PUT/DELETE with automatic read-back and diff. dryRun defaults true. [READ-ONLY MODE: returns the exact payload instead of sending it]
Inputs: path (required), method (required), body, dryRun, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 59 tools
The set has many distinct tools, but several overlaps: generic v2_get/v2_write/oa_get compete with typed readers/writers; v2_ssid_broadcast and v2_set_ap_ssid both control per-AP SSID state; v2_radar_audit and v2_dfs_check both cover DFS radar evidence; and diagnostic tools like v2_health_audit, v2_diagnostics, v2_rf_health, and v2_security_audit overlap. Descriptions are detailed, which helps, but an agent still faces real misselection risk.
Consistent v2_ snake_case prefix and set_* write convention, but read tools are mostly noun-based (v2_clients, v2_ssids, v2_events) rather than the verb_noun pattern, and oa_get/v2_get/v2_write introduce mixed verb styles. Still readable and largely predictable.
59 tools is very heavy; for a single controller domain, many typed tools duplicate what v2_get/v2_write can do, and the diagnostic/audit suite is sprawling. The broad Omada feature set provides some justification, but the surface is over-scoped.
Covers extensive read coverage plus many targeted writes, but CRUD is incomplete: no create/delete for VLANs, SSIDs, users (delete only), port profiles, DHCP reservations, or many service objects, and no firmware/backup/reboot actions. Agents can work around some gaps via generic paths, but lifecycle dead ends remain.
Maintenance
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.41MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to safely troubleshoot networks through read-only tools for device inventory, interface status, VLAN paths, BGP neighbors, route lookups, and interface error detection. Integrates with Microsoft Copilot Studio and Teams for natural-language-driven network diagnostics.-
- AlicenseAqualityCmaintenanceLets an AI assistant inspect and adjust TP-Link Omada WiFi networks by searching, describing, and calling any of roughly 1,650 Omada Open API operations through nine tools. It is read-only by default, refusing every non-GET request unless writes are explicitly unlocked, and even then returning a dry-run preview until a change is confirmed.94MIT
- AlicenseAqualityBmaintenanceEnables an LLM client to diagnose a UniFi network through 39 tools covering devices, clients, WAN and VPN state, events, metrics, traffic reports, threat summaries, and security posture audits. Guarded write tools allow blocking clients, restarting devices, and managing networks, WiFi broadcasts, and hotspot vouchers, with previews and confirmation required for changes that could cut off protected networks or the gateway.56MIT