omada-mcp
This is an MCP server that lets an AI assistant read and manage a TP-Link Omada WiFi network through a spec-driven interface to the controller's OpenAPI and legacy web APIs.
Read controller status, site list, devices, clients, and SSIDs via dedicated typed tools.
Search and inspect the full Omada OpenAPI spec (~1,650 operations) with
omada_search_apiandomada_describe_api.Call any OpenAPI endpoint with
omada_call, including automatic{omadacId}/{siteId}substitution, pagination, and query/body parameters.Use
omada_ui_callas a fallback for settings not exposed by the OpenAPI (legacy web-session API).Perform read-only operations by default; writes are blocked unless explicitly enabled.
When writes are unlocked, mutations return a dry-run preview unless confirmed with
confirm: true.Deny-list protects against irreversible actions like factory reset, firmware upgrade, deletion, and restore.
Includes shell scripts for status checks, token retrieval, authenticated API calls, config snapshots, roaming monitoring, and guided Wi-Fi surveys.
Provides a reusable Claude skill capturing Omada API gotchas and roaming measurement methods.
Integrates with TP-Link Omada controllers to read and tune WiFi networks via the Omada Open API and legacy web-session API. Provides tools for controller status, sites, devices, clients, SSIDs, API spec search/describe/call, and write-guarded configuration changes with dry-run previews.
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., "@omada-mcp What's connected to my WiFi right now, and how strong is each device?"
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.
omada-mcp
An MCP server for TP-Link Omada controllers, so an AI assistant (Claude Code, or any MCP client) can read and tune your WiFi network directly.
It is spec-driven: instead of hand-writing a tool per endpoint, it indexes the Omada Open API (~1,650 operations) and gives the model three tools to search it, inspect one operation, and call it. That means the whole API surface is reachable through nine tools.
It is read-only until you say otherwise. Every non-GET request is refused unless you explicitly unlock writes, and even then a mutation returns a dry-run preview until it is confirmed.
Built while fixing roaming on a real 3-AP home network. Full write-up with screenshots and measurements: article/ — what was actually wrong, what the numbers looked like before and after, and the two things the AI got wrong that measurement caught.
What it can do
Ask things like:
"What is connected to my WiFi right now, and how strong is each device?"
"Are any of my APs on the same channel?"
"Is fast roaming actually configured correctly?"
"Why does my phone stay on the far access point?"
"Show me the SSID settings" / "turn on the minimum RSSI threshold at -75"
Related MCP server: WhiteOmadaMcp
Tools
Tool | |
| controller info, token health, write-mode, API index, site list |
| typed reads |
| search the Omada Open API spec |
| parameters + request/response schema for one operation |
| invoke any Open API endpoint (write-guarded) |
| legacy |
Safety model
Three independent gates on any write:
OMADA_ALLOW_WRITESunset or0→ every non-GET is refused.Unlocked but no
confirm: true→ returns a dry-run preview of the exact method, URL and JSON body. Nothing is sent.A deny-list blocks the irreversible regardless of the other two: factory reset, controller restore, firmware upgrade, device/site deletion, MSP mode, and edits to the Open API app itself.
The server reads its own .env, so credentials never enter your MCP client
config.
Setup
1. Create an Open API app on the controller
Controller UI → Settings → Platform Integration → Open API → Add New App → Client Mode → give it an admin role and all site privileges → save. Copy the Client ID and Client Secret (the secret is shown only once).
Find your omadacId:
curl -sk https://<controller-ip>/api/info2. Install
git clone https://github.com/<you>/omada-mcp.git && cd omada-mcp
npm ci && npm run build
cp .env.example .env && chmod 600 .env # fill in the values
npm run smoke # verifies both transports
npm run fetch-spec # builds the API index3. Register with your MCP client
claude mcp add --scope user omada -- node "$PWD/dist/index.js"About the API index
The server first tries to download the OpenAPI document from your controller.
Hardware controllers (OC200/OC300) on 5.15.x do not serve one —
/openapi/v3/api-docs returns 404 even with a valid token. In that case it falls
back to a pinned export of the same document, taken from a controller that does
serve it (vendored from realtydev/omada-mcp,
MIT).
Treat the index as a map, not the territory: it may list endpoints your
firmware does not have. The live controller is always the authority. Re-run
npm run fetch-spec after a firmware upgrade.
Shell scripts (work without any MCP client)
scripts/omada-status.sh # reachability, token, sites, device/client counts
scripts/omada-token.sh # print an access token
scripts/omada-api.sh /sites # authenticated GET
scripts/omada-snapshot.sh <dir> # full read-only config snapshot (for rollback)
scripts/omada-roamwatch.sh # live: prints a line each time a client changes AP
scripts/omada-survey.sh -m <MAC> "Kitchen" "Bedroom" # guided walk surveyomada-roamwatch.sh and omada-survey.sh are the ones worth knowing about: they
turn "my WiFi feels bad in that room" into numbers.
Skill for Claude Code
skill/SKILL.md is a reusable skill capturing the hard-won bits: Omada API
gotchas, enum decoders, the difference between configured and on-air settings,
and a tested method for measuring roaming. Copy it to
~/.claude/skills/omada-network/ and adapt the placeholders to your own site.
Requirements
Node 22+. Tested against Omada Controller 5.15.24.21 (OC200) with EAP225, EAP625-Outdoor and EAP683 access points.
License
MIT
Available Tools
9 toolsomada_callCall any Open API endpointA
Invoke any controller Open API endpoint. Give either operationId (from omada_search_api) or method+path. {omadacId} and {siteId} are filled in automatically. Non-GET calls are refused in read-only mode, and even when writes are unlocked they return a dry-run preview unless confirm: true - show that preview to the user and get an explicit yes first.
Inputs: body, path, query, method, +3 more.
omada_clientsList connected clientsBRead-only
Clients currently connected to a site: name, MAC, IP, wired/wireless, SSID, signal, traffic. Paginated.
Inputs: page, siteId, pageSize, searchKey.
omada_describe_apiDescribe one API operationARead-only
Full detail for a single operation: path/query parameters, request-body schema and response shape. Accepts an operationId from omada_search_api, or "METHOD /path".
Inputs: operation (required).
omada_devicesList adopted devicesBRead-only
Adopted Omada devices for a site (gateways, switches, APs) with model, MAC, IP, status, uptime and firmware.
Inputs: siteId.
omada_search_apiSearch the controller APIARead-only
Search this controller's own OpenAPI spec for endpoints. Use it before omada_call whenever the exact operation is not already known - e.g. "poe port", "block client", "port forwarding", "firmware", "vlan".
Inputs: query (required), group, limit, method.
omada_sitesList Omada sitesARead-only
List the sites on this controller (siteId + name), which most other calls need.
Inputs: no named parameters.
omada_ssidsList WLANs and SSIDsBRead-only
WLAN groups on the site and the SSIDs inside each: name, band, security, guest-network and VLAN settings.
Inputs: siteId.
omada_statusOmada controller statusARead-only
Health and wiring check: controller version/info, Open API token state, write-mode, deny-list state, API index freshness, legacy web-session availability, and the site list. Run this first when anything looks off.
Inputs: no named parameters.
omada_ui_callCall the legacy web-UI APIA
Fallback transport for settings the Open API does not expose: the session API the Omada web UI itself uses (/{omadacId}/api/v2/...). Requires OMADA_WEB_USER/PASS. Same write rules as omada_call. Find paths by watching the browser network tab, or from the Omada community API notes.
Inputs: path (required), body, query, method, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly separated role: status, sites, devices, clients, and SSIDs are distinct resource views, while search_api, describe_api, call, and ui_call form a staged API workflow. There is minor overlap between omada_status (which also lists sites) and omada_sites, and between omada_call and omada_ui_call, but the descriptions make the boundaries explicit enough.
The omada_ prefix and snake_case are consistent, but the pattern is mixed: status/sites/devices/clients/ssids are noun-only names, while search_api/describe_api/call/ui_call are verb-oriented. This is readable and not chaotic, yet it does not follow a uniform verb_noun convention.
Nine tools is well-scoped: five high-level read/resource tools cover the common Omada surfaces, and four API/UI tools provide discovery, documentation lookup, and safe execution. Each tool earns its place without the set feeling bloated or thin.
The high-level tools cover the main query needs, while omada_search_api, omada_describe_api, omada_call, and omada_ui_call fill essentially any gap in the controller's exposed API or UI-facing session API. The dry-run/confirm write flow also prevents dead ends for mutating operations.
Maintenance
Related MCP Connectors
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Search 16,000+ API operations and 95 built tools by need, then call any of them by name
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Related MCP Servers
- AlicenseCqualityDmaintenanceExposes TP-Link Omada controller APIs to AI copilots, enabling listing of sites, devices, and clients, and executing arbitrary Omada API calls via natural language.8429MIT
- AlicenseBqualityCmaintenanceEnables an AI assistant to answer plain-language questions about a TP-Link Omada network — why Wi-Fi drops, which switch port a device is on, which VLAN it uses, and whether radar or interference is at play — by reading switches, access points, SSIDs, clients, topology and logs through 59 tools. It stays read-only unless two separate gates are opened, and any change is dry-run first, then read back and diffed.59MIT
- 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.5614 npmMIT
- AlicenseAqualityBmaintenanceEnables AI assistants to access every TP-Link Omada Open API operation through generated tools for searching, inspecting, and invoking controller operations such as sites, devices, clients, wireless, VPN, firewall, and hotspot management.7MIT