SkillAgentSearch skills...

omada-mcp

TP-Link Omada MCP server with automatic API discovery, validated read/write tools, network diagnostics, and runtime management for stdio and Docker.

Install / Use

claude mcp add realtydev -- npx -y github:realtydev/omada-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

75/100

Category

Automation

Supported Platforms

Claude Code
Claude Desktop

Our assessment of omada-mcp

omada-mcp scores 75/100 on our quality scale, 2566th of 2,790 Automation skills we index.

Its MCP Server is 44 KB long, well organised into 29 sections with 8 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
21/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated today, so omada-mcp is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-13. Automated pattern scan on 2026-11-13. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

omada-mcp compared with similar skills

All 4 of these similar skills score higher than omada-mcp; compare them before choosing.

SkillScoreStarsUpdatedFormat
omada-mcp (this skill)by realtydev7510todayMCP Server
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
CowAgentby zhayujie10048.0ktodayCLAUDE.md

Frequently asked questions

How do I install omada-mcp?
Run claude mcp add realtydev -- npx -y github:realtydev/omada-mcp. The install tabs above show the steps for each supported agent.
Which AI agents does omada-mcp work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is omada-mcp safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is omada-mcp still maintained?
The repository was last updated today, so omada-mcp is actively maintained.
<div align="center">

Omada MCP

Discover, diagnose, and manage your TP-Link Omada network. A Model Context Protocol server for Claude, Cursor, and other MCP clients. Search the controller's API, inspect operation schemas, and execute validated requests alongside dedicated tools for network diagnostics and configuration. Manage local stdio and Docker installations with the runtime CLI.

CI Release Container Node 24 License: MIT

</div>

Release: v0.11.0 includes 105 tools, automatic API discovery, discovery refresh, diagnostic comparisons and extended verified rollback. Use getServerInfo to confirm the running build.

You:    Why is the guest SSID slow on the upstairs AP?
Claude: (getApRadios → listClientsActivity → getSsidDetail)
        The 5 GHz radio on "AP-Upstairs" is on channel 149 at 80 MHz with 23% retries…
You:    Move it to 36 at 40 MHz, dry run first.
Claude: (setApRadio dryRun=true → setApRadio) Done. Read back and verified.

Runtime management

Use the runtime CLI for setup, doctor, status, version-pinned updates and rollback of client-managed stdio processes or a persistent local Docker service. It verifies actual running builds with getServerInfo, preserves credential files, and can adopt an existing Compose service. Setup can configure Codex, Cursor and Claude Desktop automatically; updates report client reload results and support optional desktop restarts.

Current source adds per-AP SSID overrides and read-only RF planning workflows (110 tools; 59 in read-only mode before category filtering). These additions await the next release. See per-AP overrides, RF planning, switch coverage and combined diagnosis.

Highlights

  • Automatic API discovery. searchApiOperations → describeApiOperation → executeApiOperation. Prefer the controller's live specification, with an explicit bundled fallback containing 1,676 indexed operations. Unsupported operations are identified; a catalogue entry does not prove device support. See API discovery.
  • 110 tools in the current source, including 59 in read-only mode before category filtering. Dedicated tools cover dashboards, topology, client/log diagnostics, DHCP reservations, VPN status, Wi-Fi, VLANs, firewall, routes, port forwarding, switch ports and device/client actions.
  • Traffic, RF and WAN diagnostics. Bounded history and timestamped evidence distinguish missing metrics, partial results and truncation. See network workflows and diagnostic comparisons.
  • MSP, OpenAPI 3.1 and files. Explicit MSP scope, JSON Schema 2020 validation and opt-in bounded multipart uploads/binary downloads. See file transfers.
  • Guarded configuration changes. Discovered writes default to validated previews. Radio, DHCP, SSID, switch-port, rate-limit profile and log-notification writes retain dedicated safeguards. Eligible rate-limit, DHCP, AP radio and secret-free SSID changes include drift-checked rollback receipts. Other discovered writes explicitly report that they have not been verified by reading settings back.
  • Wi-Fi audit snapshots and scoped tools. Compare AP radio configuration across matching snapshots with Wi-Fi audits, and limit dedicated/discovered operations with category scopes.
  • Explicit read-only access. MCP_TOOL_PROFILE=read-only blocks writes, including discovered operations. Controller permissions still govern which data is accessible.
  • Two API surfaces. The official Omada Open API, plus the controller's internal web UI API for features the Open API doesn't expose (ACLs, routes, port forwarding on OC200).
  • OAuth and web authentication. Open API client credentials or Fusion gateway web-session auth, with optional web UI credentials for internal-API tools. Private controller CAs are supported without disabling TLS verification.
  • stdio or HTTP. Streamable HTTP and SSE transports, health checks, CORS, and optional ngrok tunnelling.
  • WAN failover guard. An optional companion process that fixes Omada's Link Backup not failing over when a cable modem hands out a private fallback lease. See docs/wan-guard.md.
  • Know what's running. getServerInfo reports the exact version and git commit of the running server.

Quick start

1. Create Open API credentials

In your Omada controller, go to Settings → Platform Integration → Open API, add an application in Client mode, and note the Client ID, Client Secret, and Omada ID (omadacId).

Tools that use the internal web UI API (listRoutes, route/port-forward CRUD, firewall ACLs on OC200) also need OMADA_WEB_USERNAME / OMADA_WEB_PASSWORD for a local controller account. Fusion gateways without Platform Integration can use OMADA_AUTH_MODE=web instead of OAuth.

2. Add it to your MCP client

Docker (recommended), e.g. claude_desktop_config.json or .mcp.json:

{
    "mcpServers": {
        "omada": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "OMADA_BASE_URL",
                "-e",
                "OMADA_CLIENT_ID",
                "-e",
                "OMADA_CLIENT_SECRET",
                "-e",
                "OMADA_OMADAC_ID",
                "-e",
                "OMADA_SITE_ID",
                "-e",
                "OMADA_STRICT_SSL",
                "ghcr.io/realtydev/omada-mcp:latest"
            ],
            "env": {
                "OMADA_BASE_URL": "https://omada.local:8043",
                "OMADA_CLIENT_ID": "your-client-id",
                "OMADA_CLIENT_SECRET": "your-client-secret",
                "OMADA_OMADAC_ID": "your-omadac-id",
                "OMADA_SITE_ID": "your-site-id",
                "OMADA_STRICT_SSL": "false"
            }
        }
    }
}

Claude Code:

claude mcp add omada \
  -e OMADA_BASE_URL=https://omada.local:8043 \
  -e OMADA_CLIENT_ID=your-client-id \
  -e OMADA_CLIENT_SECRET=your-client-secret \
  -e OMADA_OMADAC_ID=your-omadac-id \
  -e OMADA_STRICT_SSL=false \
  -- docker run -i --rm \
     -e OMADA_BASE_URL -e OMADA_CLIENT_ID -e OMADA_CLIENT_SECRET -e OMADA_OMADAC_ID -e OMADA_STRICT_SSL \
     ghcr.io/realtydev/omada-mcp:latest

From source:

git clone https://github.com/realtydev/omada-mcp.git && cd omada-mcp
corepack enable && yarn install && yarn build
# then point your client at: node /path/to/omada-mcp/dist/index.js

3. Or run it as a shared HTTP server

docker run -d --env-file .env \
  -e MCP_SERVER_USE_HTTP=true -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
  -p 127.0.0.1:3000:3000 ghcr.io/realtydev/omada-mcp:latest

Endpoints: http://localhost:3000/mcp (Streamable HTTP) or /sse (SSE), with /healthz for health checks. See README.Docker.md for every HTTP option.

Configuration

Omada Controller

| Variable | Required | Default | Description | | -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------- | | OMADA_BASE_URL | Yes | - | Omada controller URL | | OMADA_AUTH_MODE | No | oauth | oauth for classic OpenAPI credentials, web for Fusion web-session auth | | OMADA_CLIENT_ID | OAuth mode | - | OAuth client ID | | OMADA_CLIENT_SECRET | OAuth mode | - | OAuth client secret | | OMADA_OMADAC_ID | Yes | - | Controller ID (omadacId) | | OMADA_MSP_ID | No | — | Explicit MSP context for discovered MSP routes | | OMADA_AUTH_ID | No | Controller ID | Optional separate OAuth credential principal | | OMADA_SITE_ID | No | - | Default site ID | | OMADA_WEB_USERNAME | Web mode | - | Omada web UI username | | OMADA_WEB_PASSWORD | Web mode | - | Omada web UI password | | OMADA_STRICT_SSL | No | true | SSL certificate and hostname verification | | OMADA_CA_FILE | No | — | PEM CA file/bundle added to default trust; requires strict SSL | | OMADA_API_SPEC | No | auto | API discovery source: auto, live, or bundled | | OMADA_TRANSFER_DIR | No | Disabled | Existing private directory for file transfers | | OMADA_MAX_TRANSFER_BYTES | No | 16777216 | Maximum combined upload bytes or download size, up to 64 MiB | | OMADA_TIMEOUT | No | 30000 | Request timeout (ms) |

For Fusion gateways that do not expose Platform Integration OAuth credentials, set OMADA_AUTH_MODE=web and provide OMADA_WEB_USERNAME / OMADA_WEB_PASSWORD. The server logs in through /{omadacId}/api/v2/login and uses that web session for OpenAPI requests.

MCP Server

| Variable | Required | Default | Description | | ---------------------------------- | -------- | ----------- | ---------------------------------------------------------------------------- | | MCP_SERVER_LOG_LEVEL | No | info | debug, info, warn, error, silent | | MCP_SERVER_LOG_FORMAT | No | plain | plain, json, gcp-json | | MCP_SERVER_USE_HTTP | No | false | Enable HTTP transport | | MCP_TOOL_PROFILE | No | full | full or read-only; read-only excludes writes and generic calls | | MCP_TOOL_CATEGORIES | No | — | Optional category permissions, e.g. all:r,wireless:rw; see scoped profiles | | MCP_HTTP_SESSION_IDLE_TIMEOUT_MS | No | 1800000 | Idle session lifetime; positive integer milliseconds | | MCP_HTTP_MAX_SESSIONS | No | 100 | Maximum retained and initializing HTTP/SSE sessions | | MCP_SERVER_STATEFUL | No | false | Stateful sessions

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryAutomation
Updated5h ago
Forks6

Languages

TypeScript

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info