Omada MCP server
Commit Nov 13, 2026Lets an AI client discover, diagnose, and manage TP-Link Omada networks through automated API discovery and validated configuration tools.
Also known as realtydev/omada-mcp
- Stars
- 10
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Omada MCP?
Omada lets an AI client discover, diagnose, and manage TP-Link Omada networks through automated API discovery and validated configuration tools.
Summary generated from the project's README
About Omada MCP server
Omada MCP provides a way for AI clients like Claude and Cursor to interact directly with TP-Link Omada networks. It enables automated API discovery, allowing the server to search the controller's live specification or use a bundled fallback of 1,676 operations. This allows an AI to understand and execute network commands through a structured set of tools.
Users can deploy the server via local stdio or as a persistent Docker service. The setup requires connection details such as the Omada base URL and controller ID. Authentication supports OAuth client credentials or web-session credentials for Fusion gateways. For advanced management, the runtime CLI helps with version-pinned updates, status checks, and rollbacks.
Safety is a core feature, as discovered write operations default to validated previews. The server includes dedicated tools for managing Wi-Fi, VLANs, DHCP, and switch ports. It also offers a read-only mode to prevent accidental configuration changes while still allowing for network diagnostics and audits.
What you can do with it
- 1Diagnose wireless connectivity issuesAsk the AI to investigate why a specific access point or SSID is performing poorly.
- 2Perform safe network configuration changesRequest a radio frequency change using a dry run to verify the settings before applying them.
- 3Manage network security and routingUse the internal API to manage ACLs, routes, or port forwarding on OC200 devices.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
OMADA_BASE_URLOMADA_CLIENT_IDOMADA_CLIENT_SECRETOMADA_OMADAC_IDOMADA_SITE_IDOMADA_STRICT_SSLOMADA_WAN_GUARD_ENABLED
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerealtydev/omada-mcp is public and reachablegithub.com/realtydev/omada-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/realtydev/omada-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View 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.
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 |
MCP_HTTP_PORT |
No | 3000 |
HTTP port |
MCP_HTTP_TRANSPORT |
No | stream |
stream or sse |
MCP_HTTP_BIND_ADDR |
No | 127.0.0.1 |
Bind address |
Tools
Omada MCP questions
How can I restrict the server to read-only mode?
You can set the MCP_TOOL_PROFILE environment variable to 'read-only', which blocks all write operations and generic calls.
What authentication methods are supported?
The server supports OAuth via Open API client credentials, web-session authentication for Fusion gateways, and optional web UI credentials for internal-API tools.
Does it support automatic API discovery?
Yes, it features automatic API discovery that prefers the controller's live specification with a bundled fallback of 1,676 operations.