omada-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| OMADA_SITE_ID | No | Site hex id or name; names are resolved to the hex id required by controller URLs. | first site |
| OMADA_BASE_URL | Yes | Omada controller base URL, e.g. https://host:8043. Required. Scheme-less values get https://...:8043; http:// defaults to port 8088. Must not embed credentials. | |
| OMADA_ENV_FILE | No | Explicit path to a dotenv file. A missing file is a hard error. Lets several hosts share one configuration file. | |
| OMADA_PASSWORD | Yes | Local controller account password. Required. Never printed or logged. | |
| OMADA_USERNAME | Yes | Local controller account username. Required. Viewer is sufficient for reads; use a dedicated Admin account for writes. | |
| OMADA_CA_BUNDLE | No | PEM bundle containing the controller's CA. | system store |
| OMADA_READ_ONLY | No | Default true fails closed and refuses every non-read-only tool before argument validation. Set false to enable allowlisted writes. | true |
| OMADA_SITE_NAME | No | Site display name, e.g. Home. | first site |
| OMADA_VERIFY_SSL | No | Set false to disable chain and hostname checks. Not for production. | true |
| OMADA_SCHEMA_MODE | No | tools/list schema detail: slim (default, smaller payload) or full. | slim |
| OMADA_STRICT_X509 | No | Set false to clear Python 3.13+ VERIFY_X509_STRICT while keeping chain and hostname checks; useful for self-signed certificate errors. | true |
| OMADA_WRITE_TOOLS | No | Comma-separated exact write tool names to enable. Wildcards and all are rejected. Both OMADA_READ_ONLY=false and this allowlist are required to expose or invoke write tools. | |
| OMADA_SNAPSHOT_DIR | No | Override directory for pre-write JSON snapshots and audit.jsonl. | platform state dir |
| OMADA_COMPACT_OUTPUT | No | Emit single-line compact JSON in tools/call content[0].text. Set false for 2-space indented JSON. | true |
| OMADA_TIMEOUT_SECONDS | No | Per-request timeout in seconds. | 30 |
| OMADA_TLS_SERVER_NAME | No | Optional TLS server_hostname override, e.g. Omada, when connecting by IP against the controller's built-in certificate. | |
| OMADA_TOOL_CATEGORIES | No | Optional comma-separated tool categories to expose in tools/list: core, diagnostics, switch, wifi, routing, security, rollback. | all |
| OMADA_MANAGEMENT_CIDRS | No | Comma-separated IPv4 hosts/CIDRs, in addition to the controller host IP, protected from lockouts during VLAN isolation, DHCP pool, or deny-ACL writes. | |
| OMADA_USE_SYSTEM_PROXY | No | System/registry proxies are ignored by default. Set true only when a proxy is genuinely required. | false |
| OMADA_MIN_INTERVAL_SECONDS | No | Minimum spacing between controller calls; raise to 0.8 on large sites. | 0.25 |
| OMADA_WRITE_INTERVAL_SECONDS | No | Minimum serialized spacing between write requests. Writes never auto-retry -1600. | 1.0 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access by default to a TP-Link Omada SDN controller through its Web API v2. Thirty-five read-only tools are always available, including list_sites, get_site_info, get_config_snapshot, diff_config_snapshots, network_audit, get_switch_ports, get_ap_radios, get_wan_status, get_topology, diagnose_client, diagnose_wan, list_devices / list_clients, get_device / get_client, and explain_error. Most tools accept an optional site name/ID. Optional write tools remain hidden and disabled unless both OMADA_READ_ONLY=false and OMADA_WRITE_TOOLS explicitly allowlist them. Timestamps are UTC ISO-8601. Error messages include the controller's numeric errorCode and a fix hint.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_devicesC | List all managed network devices (APs, switches, gateways) on the site with MAC, model, firmware, IP, uptime… |
| list_clientsC | List connected clients (WiFi and wired) with MAC, IP, SSID, AP, VLAN, traffic counters, session duration and… |
| list_wifi_clientsB | List only wireless clients, same fields as list_clients. |
| list_wired_clientsB | List only wired clients, same fields as list_clients. |
| get_deviceC | Get one device by MAC address or device name. |
| get_clientB | Get one client by MAC address, hostname or IP address. |
| list_wlansB | List configured WLANs/SSIDs with band, VLAN, security type and guest flag. |
| get_site_infoB | Site summary: name, id, WAN/LAN/WLAN state, device and client counts, controller version. |
| list_sitesB | List sites visible to the authenticated Viewer or Admin account with site IDs, names, connectivity flags, and… |
| network_auditB | One-call read-only health audit checking WAN state/packet loss, offline devices, pending firmware upgrades… |
| explain_errorC | Decode an Omada Web API errorCode (e.g. -1600, -33717, -33726, -1505, -1001, -30109, -41011, -44116) into its… |
| get_config_snapshotC | Read-only snapshot of LAN networks (both collection and /interface endpoints), gateway ACLs, IP/port groups… |
| diff_config_snapshotsC | Deterministically compare two get_config_snapshot payloads… |
| search_clientsB | Search online and offline/historical clients by MAC, name, hostname, IP, SSID, or VLAN/network, with… |
| list_lan_networksC | List configured LAN/VLAN networks merging setting/lan/networks and /interface… |
| list_dhcp_reservationsB | List static DHCP reservations configured on the site (works for offline clients too). |
| list_aclsC | List gateway, switch, or EAP ACL rules (setting/firewall/acls?type=0|1|2) with policy, source/destination… |
| list_ip_groupsB | List profile groups (IP groups type=0, port groups type=1, MAC groups type=2) with entry counts and ACL… |
| list_port_forwardsB | List gateway NAT port forwarding and DMZ-mapped rules. |
| list_static_routesB | List configured gateway static routes (destinations, next hop, interface, metric). |
| get_network_servicesC | Summarize UPnP, DNS proxy, mDNS reflector rules and profiles, secret-redacted DDNS configuration, and… |
| list_logsB | Query controller site logs ('alerts', 'events', or 'audit') with time window, optional level filter, and row… |
| get_switch_portsC | Inspect per-port link status, speed/duplex, PoE delivery & switch budget, active port profile/VLANs… |
| get_ap_radiosC | Inspect an AP's 2.4G/5G/5G2/6G radios: channel, width, TX power, channel utilization, interference… |
| get_rf_scanC | Read the latest cached RF scan status/neighbor results (empty channels list if no scan was triggered) and… |
| get_wan_statusB | Inspect gateway WAN link state, gateway/DNS/WAN IP, failover/load-balance mode, latency/packet loss health… |
| list_vpn_tunnelsB | List WireGuard, OpenVPN, IPsec, and SSL/L2TP VPN tunnel state and configured profiles… |
| get_topologyB | Build the site's Gateway -> Switch(port) -> AP/Switch uplink tree with device counts. |
| get_security_statusC | Summarize IPS/IDS enablement, recent threat events, attack defense limits, WIDS/WIPS, and rogue AP detections… |
| diagnose_clientC | Correlate client signal/link state, connection history, parent AP radio or switch port telemetry, and recent… |
| diagnose_wanC | Correlate live WAN link state, latency/packet loss, speedtest, VPN tunnel health, and gateway alerts/events… |
| list_port_profilesB | List switch port profiles (All, Disable, custom VLAN/PoE profiles). |
| list_wlan_groupsC | List configured WLAN groups and their SSIDs for assigning APs cleanly. |
| list_policy_routesB | List policy routing rules (gracefully reports unavailability if no gateway exists). |
| list_lan_dns_rulesB | List local LAN DNS records (gracefully warns on controller versions without LAN DNS). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 35 tools
Most tools target clearly distinct resources (devices, clients, WLANs, ACLs, VPN tunnels, WAN status, logs), and the get_* vs list_* vs diagnose_* split is meaningful. Overlap exists between list_clients and the list_wifi_clients/list_wired_clients subsets, and between network_audit/get_config_snapshot/diagnose_wan which all report WAN health from different angles, but descriptions make the intended use reasonably clear.
Almost all names follow a consistent snake_case verb_noun pattern (list_*, get_*, diagnose_*, search_*, diff_*), with list_/get_ used predictably for collections vs single records. The one deviation is the noun-style 'network_audit', and 'explain_error'/'diff_config_snapshots' are slightly off-pattern but still readable.
35 tools is heavy and exceeds a comfortable range, though the breadth reflects a genuinely wide network-controller domain (sites, devices, clients, WiFi, ACLs, VPN, routing, DNS, RF, logs). Some tools are thin convenience wrappers (list_wifi_clients, list_wired_clients, get_rf_scan) that could be parameters of existing tools rather than separate entries.
The read-only observability surface is thorough: inventory, topology, health audits, config snapshots with diffing, diagnostics, and error decoding cover the monitoring lifecycle well. The main gap is that the server is entirely read-only—no mutations for DHCP reservations, ACLs, WLANs, or firmware upgrades—so flows like 'detected pending firmware' dead-end without an action tool.