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-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| omada-mcp (this skill)by realtydev | 75 | 10 | today | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.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.
Skill content
View source on GitHubOmada 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.
</div>Release: v0.11.0 includes 105 tools, automatic API discovery, discovery refresh, diagnostic comparisons and extended verified rollback. Use
getServerInfoto 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-onlyblocks 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.
getServerInforeports 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 needOMADA_WEB_USERNAME/OMADA_WEB_PASSWORDfor a local controller account. Fusion gateways without Platform Integration can useOMADA_AUTH_MODE=webinstead 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
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
