omada-mcp

A Model Context Protocol server for TP-Link Omada SDN controllers — zero dependencies, read-only by default, and honest about every failure.

Your Omada controller already knows which AP is overloaded, which client is sitting on the guest VLAN, and which switch dropped a port. omada-mcp hands that to Claude, Cursor, Hermes or any other MCP host — as 33 read-only tools that return clean JSON (plus 47 optional write tools behind an explicit allowlist, plus --watch and --export-metrics monitoring modes), with a self-test that tells you exactly what to fix when something is wrong.

uvx omada-mcp --doctor

omada-mcp doctor v1.2.1 on Linux-6.8 (Python 3.12.7)
------------------------------------------------------------------
PASS env      /home/you/.config/omada-mcp/.env | url=https://192.0.2.10:8043 user=omada-readonly password=set (24 chars)
PASS tls      verified against /home/you/.config/omada-mcp/controller-ca.pem (serverName=Omada) | reachable, omadacId=0123456789abcdef01234567, controllerVer=6.2.10.17, family=software-6.x
PASS login    token accepted for omada-readonly (role=Viewer, scope=all sites, cookie=TPOMADA_SESSIONID), Csrf-Token round-trip OK
PASS site     Home (89abcdef0123456789abcdef) site 1 of 1; matched OMADA_SITE_NAME=Home
PASS tools    list_devices -> 7 device(s); 33 read-only tools registered (0 write tool(s) enabled), 23 client(s)
PASS write    disabled (OMADA_WRITE_TOOLS is empty; read-only tools only)
------------------------------------------------------------------
6/6 checks passed
Ready: `omada-mcp` will serve 33 read-only tools on stdio.

Add --json (omada-mcp --doctor --json) for machine-readable output validated against schemas/doctor.schema.json. JSON output redacts local .env and OMADA_CA_BUNDLE filesystem paths to origin labels (OMADA_ENV_FILE, cwd, appdata, xdg, environment) so reports are safe to paste into issues.

Why this exists

Omada exposes two unrelated APIs and the documentation blurs them:

omada-mcp speaks the Web API. That means: create a local Viewer account, put three values in a dotenv file, and you are done. No OAuth app, no client secret rotation, no per-firmware integration screen.

Three properties make it safe to hand to an LLM:

• Read-only tools only. Every tool is annotated readOnlyHint: true, and OMADA_READ_ONLY=true fails closed: a call to anything not declared read-only is refused with -32003 before lookup, so a future write tool cannot leak past the switch.
• No secret echo. The password never appears in output (only set (N chars)), the session token is never logged, and WLAN pre-shared keys are redacted — list_wlans reports hasPresharedKey: true instead.
• Errors that carry the fix. Controller error codes are translated (-1505, -1600, -33726, -41011, -44116, …) and every message ends with the action to take.

Install

# from git (works today)
uvx --from git+https://github.com/falehsub/omada-mcp omada-mcp --doctor

# from PyPI
uvx omada-mcp --doctor

# or install the command
uv tool install omada-mcp     # or: pipx install omada-mcp
pip install omada-mcp         # plain pip

# from a local checkout:
git clone https://github.com/falehsub/omada-mcp && cd omada-mcp
uv tool install .             # installs the `omada-mcp` command from the checkout

Requires Python 3.10+ and nothing else. There are no runtime dependencies — urllib, ssl, json and argparse are the whole stack, which keeps the supply chain at zero.

Configure

mkdir -p ~/.config/omada-mcp
cp .env.example ~/.config/omada-mcp/.env
chmod 600 ~/.config/omada-mcp/.env
$EDITOR ~/.config/omada-mcp/.env

The minimum is three lines:

OMADA_BASE_URL=https://192.0.2.10:8043
OMADA_USERNAME=omada-readonly
OMADA_PASSWORD=...

Where configuration is read from

Highest priority first — the first hit wins per variable, and the process environment always overrides a file:

1. process environment (export OMADA_BASE_URL=...)
2. $OMADA_ENV_FILE — an explicit path (missing file = hard error, so a typo cannot silently fall through)
3. ./.env — relative to the working directory (handy for per-project setups)
4. %APPDATA%\omada-mcp\.env — Windows only, where a Windows user expects a per-user config
5. ~/.config/omada-mcp/.env (or $XDG_CONFIG_HOME/omada-mcp/.env)

Windows

Everything is supported natively — no WSL, no MSYS. The console script installs as omada-mcp.exe, and uvx / uv tool install behave exactly as on POSIX.

New-Item -ItemType Directory -Force "$env:APPDATA\omada-mcp" | Out-Null
Copy-Item .env.example "$env:APPDATA\omada-mcp\.env"
notepad "$env:APPDATA\omada-mcp\.env"

Windows-specific behaviour, handled for you:

• Config location. %APPDATA%\omada-mcp\.env is picked up before ~/.config/omada-mcp/.env, so the usual Windows location just works.
• Encoding. Stdio is forced to UTF-8. The console code page (cp1252, cp1256, cp437 …) cannot encode an Arabic or CJK SSID, and the failure mode is a UnicodeEncodeError in the middle of a session — this never reaches you.
• Line endings. Frames are written with a single \n; text mode would otherwise emit \r\n and strict clients can mis-frame. Incoming \r\n frames are accepted too.
• Proxies. System/WinINET proxies are ignored by default (OMADA_USE_SYSTEM_PROXY=true to opt in).
• File permissions. API keys live in your user profile; --doctor skips the POSIX chmod advice on Windows rather than handing you a command that does nothing. To restrict the file to your account: icacls "%APPDATA%\omada-mcp\.env" /inheritance:r /grant:r "%USERNAME%:F".

get_device/get_client accept a MAC in any format (AA-BB-CC-DD-EE-FF, aabbccddeeff, aa:bb:cc:dd:ee:ff) as well as a hostname or IP, so PowerShell output pastes straight in.

All variables

omada-mcp --show-config prints the resolved values with the password masked; omada-mcp --doctor validates them.

Connect an MCP host

The server is plain stdio: a host runs uvx omada-mcp, then speaks JSON-RPC on stdin/stdout. The OMADA_ENV_FILE environment variable lets several hosts share one configuration file.

Hermes Agent

hermes mcp add omada --command uvx --args omada-mcp \
  --env OMADA_ENV_FILE=$HOME/.config/omada-mcp/.env

Or in ~/.hermes/config.yaml:

mcp_servers:
  omada:
    command: uvx
    args: ["omada-mcp"]
    env:
      OMADA_ENV_FILE: /home/you/.config/omada-mcp/.env

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "omada": {
      "command": "uvx",
      "args": ["omada-mcp"],
      "env": {
        "OMADA_ENV_FILE": "/home/you/.config/omada-mcp/.env"
      }
    }
  }
}

A copy lives at examples/claude_desktop_config.json.

Claude Code

claude mcp add omada --env OMADA_ENV_FILE=$HOME/.config/omada-mcp/.env -- uvx omada-mcp
claude mcp list

Cursor

.cursor/mcp.json in the project, or the global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "omada": {
      "command": "uvx",
      "args": ["omada-mcp"],
      "env": { "OMADA_ENV_FILE": "/home/you/.config/omada-mcp/.env" }
    }
  }
}

Anything else

Any host that can spawn a process and speak newline-delimited JSON-RPC 2.0 works:

{
  "mcpServers": {
    "omada": {
      "command": "uvx",
      "args": ["omada-mcp"],
      "env": { "OMADA_ENV_FILE": "/home/you/.config/omada-mcp/.env" }
    }
  }
}

From a git checkout instead of PyPI:

uvx --from git+https://github.com/falehsub/omada-mcp omada-mcp --doctor

Tools

Thirty-three read-only tools (~11.3k tokens in tools/list) are always registered; 47 optional write tools stay hidden and disabled until both OMADA_READ_ONLY=false and OMADA_WRITE_TOOLS allowlist them explicitly. list_clients windowing is bounded by limit (default 500, max 5000) and de-duplicated by MAC.

Read-only tools (always available)

Opt-in write tools (OMADA_READ_ONLY=false + OMADA_WRITE_TOOLS)

Every write tool defaults dryRun=true, captures a pre-mutation JSON snapshot under OMADA_SNAPSHOT_DIR, requires confirm="<tool>:<target>" when dryRun=false, verifies state on read-back, and never auto-retries on -1600.

omada-mcp --list-tools prints active descriptors without touching the network (add --all to inspect all 80 tools including non-allowlisted writes).

Every descriptor in tools/list declares MCP annotations and an MCP 2025-06-18 outputSchema, so hosts can auto-approve reads and validate structured results:

{
  "name": "list_devices",
  "title": "List Omada devices",
  "outputSchema": {
    "type": "object",
    "properties": {
      "items": { "type": "array" },
      "count": { "type": "integer", "minimum": 0 }
    },
    "required": ["items", "count"]
  },
  "annotations": {
    "title": "List Omada devices",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  }
}

Output shape (content vs structuredContent)

• List tools (list_devices, list_clients, list_wifi_clients, list_wired_clients, search_clients, list_wlans, list_wlan_groups, list_lan_networks, list_port_profiles, list_dhcp_reservations, list_acls, list_ip_groups, list_port_forwards, list_static_routes, list_policy_routes, list_lan_dns_rules, list_vpn_tunnels, list_logs): content[0].text is serialized as a bare JSON array ([{...}, ...]), while structuredContent is an object matching outputSchema: {"items": [...], "count": <int>}. Callers parsing content[0].text (for example migrating from wrapper objects like {"devices": [...]}) receive a JSON list directly, whereas MCP 2025-06-18 hosts read structuredContent.items and structuredContent.count.
• Object tools (get_device, get_client, get_site_info, get_network_services, get_switch_ports, get_ap_radios, get_rf_scan, get_wan_status, get_topology, get_security_status, diagnose_client, diagnose_wan, network_audit, explain_error, get_config_snapshot, and write envelopes): both content[0].text and structuredContent contain the same JSON object matching outputSchema.

omada-mcp --list-tools prints active descriptors without touching the network; omada-mcp --list-tools --all prints all 80 descriptors (add --compact for single-line JSON). Direct controller connections reuse persistent HTTP/1.1 keep-alive TLS sockets (UrllibTransport), and composite troubleshooters (network_audit, diagnose_client, diagnose_wan, get_config_snapshot, --watch / --export-metrics) deduplicate repeated site-wide GETs within a single invocation via an ephemeral per-call cache (OmadaClient.scoped_cache()).

Watch mode, Prometheus metrics & Docker

Both monitoring modes reuse one persistent authenticated OmadaClient session and enforce >= 0.8 s pacing so they never evict shared sessions:

# Stream JSON telemetry snapshot + event diffs (wan_failover, ap_retry_spike, weak_client_rssi, dhcp_pool_utilization)
omada-mcp --watch --interval 30

# One-shot Prometheus text exposition
omada-mcp --export-metrics

# Persistent /metrics HTTP endpoint (cached with >= 5 s scrape TTL + /healthz)
omada-mcp --export-metrics --metrics-port 9108 --metrics-host 127.0.0.1

Build and run the non-root container (OMADA_READ_ONLY=true by default):

docker build -t omada-mcp .
docker run --rm -i --env-file ~/.config/omada-mcp/.env omada-mcp --doctor
docker run --rm -p 9108:9108 --env-file ~/.config/omada-mcp/.env omada-mcp --export-metrics --metrics-port 9108 --metrics-host 0.0.0.0

Safety model

Troubleshooting

Run omada-mcp --doctor first — it names the failing phase and the fix. The table below maps the symptoms it cannot see.

Compatibility

See docs/compatibility.md for the full compatibility table.

• Software controller v6.x — read-only path (--doctor --json and all 33 read-only tools) verified live on v6.2.10.17 (TPOMADA_SESSIONID), and 20 baseline read-only tools plus controller-native write CRUD (create/update/delete_lan_network with explicit ipaddrStart/ipaddrEnd pools, set_vlan_dhcp_pools, upsert/delete_dhcp_reservation, create/replace/delete_ip_group, create/update/set_acl_rule_status/delete_gateway_acl including the 6-step swap, create_switch_acl/create_eap_acl with typed toggle/update/delete lifecycle, create/update/delete_ssid with PSK redaction, upsert/delete_port_forward, upsert/delete_static_route, upsert/delete_mdns_rule, set_upnp dry-run + live disable + -33001 gateway check, -33598 on hardwareless isolation, Viewer -1007 -> insight/clients fallback, and -41011/not-found probes) verified live against an isolated Docker Omada Controller v6.2.14.11; client fixed-IP lease-delayed behavior (set_client_fixed_ip/release_client_fixed_ip), client actions, and device controls (update_device, reboot_device) are covered by the stateful mock controller.
• Software controller v5.x — expected (v5.13.30.8 core auth/list shapes supported; awaiting a --doctor --json capture via the issue template).
• OC200 / OC300 hardware & TPEAP_SESSIONID builds — expected (--doctor detects both TPOMADA_SESSIONID and TPEAP_SESSIONID, handles legacy result.omadacId login shapes, and reports hardware-5.x / hardware-6.x). Run omada-mcp --doctor --json and submit a Controller Compatibility Report.

Development

git clone https://github.com/falehsub/omada-mcp && cd omada-mcp
python -m unittest discover -s tests -v     # stdlib tests; loopback HTTP only
python -m omada_mcp.cli --help              # after: pip install -e .
uvx --from . omada-mcp --doctor             # what an external user does

# uv caches the build of a local *path* and does not rebuild when the source
# changes (`--refresh` does not help). Force a fresh environment while iterating:
UV_CACHE_DIR=$(mktemp -d) uvx --from . omada-mcp --doctor

For a repeatable live read-only sweep, use an explicit isolated lab configuration:

python scripts/read_selftest.py --env-file /path/to/isolated/viewer.env

The sweep forces read-only mode, blocks mutations at the transport boundary, and reports pass/fail/skip, elapsed time and request counts without controller payloads. Hardware-dependent checks are skipped when the site has no matching devices or clients. Configuration, service and routing exports expose known fields only; diagnostic snapshots are not full controller backups.

See the local review and prioritized improvements for measured results, limitations and the next development priorities.

Layout:

src/omada_mcp/config.py         dotenv discovery, validation, base-URL normalisation, write allowlist
src/omada_mcp/client.py         Web API v2 client: auth, pagination, write gate, snapshots/audit, errors
src/omada_mcp/_helpers.py       shared v5/v6 diagnostics, secret redaction, topology & capability helpers
src/omada_mcp/tools.py          33 read-only tools + 47 write descriptors, projections, outputSchema
src/omada_mcp/write_tools.py    read-modify-write handlers, CIDR packer, anti-stranding, rollback, 6-step swap
src/omada_mcp/monitor.py        single-session --watch JSON diff streamer & --export-metrics Prometheus exporter
src/omada_mcp/server.py         JSON-RPC stdio server, fail-closed gates, strict arg/bool checks
src/omada_mcp/doctor.py         6-phase self-test (env, tls, login, site, tools, write) with --json
Dockerfile                      minimal non-root container (stdio default, --watch, --export-metrics)
schemas/doctor.schema.json      JSON Schema for --doctor --json
docs/compatibility.md           controller family and cookie compatibility matrix
docs/write-support.md           write-support contract, verified endpoints, and controller traps
tests/mock_controller.py        stateful Web API v2 mock controller with fault injection
tests/test_bridge.py            read-only bridge, M1 diagnostics, M3 watch/metrics & protocol tests
tests/test_write_support.py     write-gate, RMW flows, anti-stranding, rollback & fault-injection tests
skills/omada-controller/        agent skill: field notes for the Omada API itself

The API notes in skills/omada-controller/SKILL.md document the parts of the controller that are not in any public reference: session expiry semantics, CIDR packing limits, dual-pool DHCP bodies, and the endpoints that are Admin-only.

Contributing & releasing

• Pull requests only: Develop changes on a branch and open a Pull Request targeting main rather than pushing directly to main. Every PR runs the CI matrix across Ubuntu and Windows (Python 3.10–3.14) via .github/workflows/ci.yml.
• PyPI publishing (Trusted Publishing / OIDC): Releases publish to PyPI via .github/workflows/publish.yml using GitHub Actions OIDC tokens (bound to the pypi GitHub Environment) on published GitHub Releases or manual workflow_dispatch runs for a release tag, without stored PyPI API tokens.

Write support

Read-only mode remains the default (OMADA_WRITE_TOOLS defaults empty and write tools are hidden). Opt-in writes follow the contract in docs/write-support.md — explicit OMADA_WRITE_TOOLS allowlist, dryRun=true default, confirm="<tool>:<target-id>", pre-write snapshots + audit.jsonl, whole-object verification, and anti-stranding checks. Use a dedicated Admin local account separate from your read bridge and web UI to avoid session eviction. Firmware upgrades remain unshipped pending a maintenance-window policy.

Roadmap

Read-only inspection, composite diagnostics (get_switch_ports, get_ap_radios, get_wan_status, get_topology, diagnose_client, diagnose_wan), --doctor --json, network_audit, the 80-tool control surface (rollback_from_snapshot + anti-stranding switch/AP/routing/DNS/ACL/client controls), --watch/--export-metrics, and non-root Docker packaging are implemented on main. Next items in ROADMAP.md include MCP Registry server.json, automated controller compatibility checks, multi-site workflows and configuration drift reports. PyPI installation is available.

License

MIT — see LICENSE.

Not affiliated with TP-Link. Omada is a trademark of TP-Link Technologies. This server calls an undocumented internal API; a controller firmware update can change it, which is exactly why --doctor exists.