Skip to main content
Glama

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?"

v2_client_history, v2_ssids, v2_site_settings

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?"

v2_interference_audit, v2_channel_util

Non-WiFi interference measured by the access points themselves, kept apart from ordinary congestion

"Did radar push my 5 GHz off its channel?"

v2_radar_audit, v2_dfs_check

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?"

v2_past_connections, v2_topology, v2_switch_ports

The device, port, VLAN, link speed and PoE state

"Is my network configured safely?"

v2_security_audit, v2_health_audit

Ranked findings, each with the exact fix and its blast radius

"Turn off 802.11r on the home SSID."

v2_set_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.env

Then 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=true

Writes 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

  1. Every write is read back and diffed. A controller that returns Success and changes nothing is reported as REVERTED, not as success. Omada does this on several endpoints.

  2. Writes default to dryRun: true.

  3. 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.

  4. Human units at the boundary. You say channel: 100 and widthMHz: 40; the server handles the fact that Omada wants a 1-based index into channelRange and (MHz/20)+1.

  5. Destructive changes preview their casualties. Setting an RSSI kick threshold or a minimum data rate lists the clients that would be affected before sending.

  6. 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 (value 1) on WPA2-PSK, and WPA2/WPA3 transition mode. Omada's PMF enum is 1 = Mandatory, 2 = Capable, 3 = Disabled; 1 is 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

-1001

Bad or missing parameters — the endpoint exists. Usually a required sibling field.

-1600

Path does not exist on this build.

-1005

Licence gate.

-1007

Your account's role lacks that page.

-1

Feature needs hardware you do not have.

-30165

Login refused: 2FA is enabled. The v2 login API cannot complete it.

-33411

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 controller

The 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 tools
oa_getA
Read-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_alertsB
Read-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_radiosA
Read-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_logsA
Read-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_utilA
Read-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_historyA
Read-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_clientsA
Read-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_survivalA
Read-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_settingsA
Read-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_userA
Destructive

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_checkA
Read-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_diagnosticsA
Read-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_endpointsA
Read-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_eventsB
Read-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_getA
Read-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_auditA
Read-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_auditA
Read-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_networksB
Read-onlyIdempotent

Every VLAN: name, tag, subnet, DHCP scope, IGMP/MLD snooping, DHCP guard, purpose. Flags networks with snooping off.

Inputs: siteId.

v2_log_diagnoseA
Read-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_settingsB
Read-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_modeA
Read-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_notificationsB
Read-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_connectionsB
Read-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_statsA
Read-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_auditA
Read-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_healthB
Read-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_planningA
Read-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_apsA
Read-onlyIdempotent

Neighbouring/rogue APs seen by your own APs — SSID, BSSID, channel, signal, security. Empty until a scan has run.

Inputs: siteId.

v2_security_auditA
Read-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_servicesB
Read-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_balanceB
Idempotent

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_ssidA
Destructive

⚠ 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_radioA
Idempotent

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_kickA
Idempotent

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_ssidA
Idempotent

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_igmpA
Idempotent

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_portA
Idempotent

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_profileA
Idempotent

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_pvidA
Idempotent

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_bulkA
Idempotent

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_serviceA
Idempotent

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_featureB
Idempotent

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_roamingA
Idempotent

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_ssidA
Idempotent

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_controlA
Idempotent

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_stpA
Idempotent

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_settingsB
Read-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_speedtestA
Idempotent

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_broadcastC
Read-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_ssidsA
Read-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_statusA
Read-onlyIdempotent

Login check: controller version, account, role, and hours left on a temporary account. Call this first.

Inputs: no named parameters.

v2_switchesC
Read-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_portsA
Read-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_statsB
Read-onlyIdempotent

Per-switch statistics view: per-port operation, speeds, PoE and traffic totals as the Statistics page shows them.

Inputs: switchMac (required), siteId.

v2_topologyA
Read-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_usersA
Read-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_profilesB
Read-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_wanB
Read-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_writeC
Idempotent

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

    B3.1/5.0

    Scored across 59 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      41
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Lets 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.
      9
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      56
      MIT