omada-mcp

A Model Context Protocol server for the TP-Link Omada SDN Controller. It lets an AI assistant read and safely modify an Omada network through well-defined, capability-gated tools.

Built as a security-first companion to mbentley/docker-omada-controller.

• Talks to the Omada Open API (OAuth2 client-credentials) — not the internal cookie/CSRF API. The full v1 OpenAPI spec is captured in docs/openapi/.

• 21 tools covering reads (sites, devices, clients, SSIDs, site settings, events, logs) and writes (reboot, block/unblock/reconnect client, rate limit, LED, SSID config, AP radio config, site roaming, band steering).

• Capability profiles gate what the assistant can do — safe-read is the default and exposes only read tools. Writes require explicit opt-in via env var.

• Every write tool defaults to dryRun: true — preview the diff before applying. After apply, the controller is re-read and any silent overrides are surfaced.

Verified against Omada Controller 6.2.10.17 (apiVer 3).

Status — local use only

This release is designed to run on the same machine as your MCP client (e.g. your laptop running Claude Code or Claude Desktop). It is not ready to be deployed as a long-lived service on your home server, alongside the controller, or anywhere else network-reachable.

Why:

• The server speaks stdio only today. Your MCP client launches it as a subprocess per session and pipes JSON-RPC over stdin/stdout — there is nothing to "connect to" over a network.

• HTTP transport is scaffolded but not implemented. The env-var plumbing exists (MCP_TRANSPORT, MCP_HTTP_ENABLE, MCP_HTTP_BIND, MCP_HTTP_PORT) so future work doesn't reshape the project — but today setting MCP_TRANSPORT=http throws a clear "use stdio" error.

• There is no authentication in front of the server. If HTTP were enabled today, anything reaching its port could invoke the write tools. A safe hosted deployment needs at minimum Bearer-token auth plus a nginx / VPN topology in front; that's a focused next phase, not a deploy-it-as-is.

So: even though docker-compose.example.yml shows the eventual pairing with mbentley/omada-controller, the only currently-supported deployment is run it locally, beside whatever MCP client is using it.

Quick start

1. Create an Open API client in the controller

Follow docs/SETUP.md: in the controller go to Settings → Platform Integration → Open API, create a client-credentials app, and capture the client ID, client secret and omadacId.

2. Configure .env

Copy .env.example to .env in the repo root and fill in:

OMADA_BASE_URL=https://omada.local:8043
OMADA_CLIENT_ID=...
OMADA_CLIENT_SECRET=...
OMADA_OMADAC_ID=...
OMADA_SITE_ID=...                    # optional; tools require an explicit siteId otherwise
OMADA_VERIFY_TLS=false               # for self-signed controller certs
OMADA_CAPABILITY_PROFILE=safe-read   # safe-read | ops-write | admin

.env is git-ignored. Keep it on the machine that will run the server.

3. Pick a way to run it (choose ONE)

Both options run the server on whatever machine the MCP client is on. There's no operational difference — pick whichever you find simpler.

Option A — Node directly (recommended; no Docker needed)

npm install
npm run build

Then point your MCP client at the compiled entry point. For Claude Desktop that means editing claude_desktop_config.json:

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": ["/abs/path/to/omada-mcp/dist/index.js"]
    }
  }
}

The server finds .env automatically — it looks next to the compiled entry point (i.e. <repo>/dist/index.js → <repo>/.env), then in the working directory, then at whatever path OMADA_DOTENV_PATH points at. Any one of those three is enough.

If the server starts but fails with "Invalid configuration: …" telling you the required vars are undefined, your .env is not where it's looking. Either move/copy .env next to dist/index.js, or set OMADA_DOTENV_PATH explicitly:

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": ["/abs/path/to/omada-mcp/dist/index.js"],
      "env": {
        "OMADA_DOTENV_PATH": "/abs/path/to/omada-mcp/.env"
      }
    }
  }
}

The MCP client's env block is also a perfectly good place to put the Omada config inline if you'd rather not keep a .env file at all — e.g. set OMADA_BASE_URL, OMADA_CLIENT_ID, OMADA_CLIENT_SECRET, OMADA_OMADAC_ID directly there.

Option B — Local Docker build

If you'd rather not have Node installed locally:

docker build -t omada-mcp:local .

This builds the image on your machine with the tag omada-mcp:local. No registry is involved. Then in your MCP-client config:

{
  "mcpServers": {
    "omada": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "--env-file", "/abs/path/to/omada-mcp/.env",
               "omada-mcp:local"]
    }
  }
}

The MCP client runs docker run -i --rm per session; the container exits when the session ends.

Note on ghcr.io/<owner>/omada-mcp:latest references

Some legacy snippets you may see reference an image tag like ghcr.io/<owner>/omada-mcp:latest. That image does not exist — it is a placeholder for a hypothetical published image on GitHub Container Registry. The CI workflow in this repo builds the Docker image but does not push it anywhere (push: false).

You only need a public registry image if you want to install on multiple machines without each one rebuilding from source. To make that real you'd need to:

1. Push this repo to GitHub under your own account/org (e.g. your-name/omada-mcp).

2. Edit .github/workflows/ci.yml to add permissions: packages: write, a docker/login-action step against ghcr.io, and flip push: false to push: true with a real tag (tags: ghcr.io/your-name/omada-mcp:latest).

3. Reference the resulting image at ghcr.io/your-name/omada-mcp:latest.

For a single-laptop setup you don't need any of this — Option A or B above is the right path.

Tool catalog

All read tools are tagged safe-read. Every write tool defaults to dryRun: true — pass dryRun: false to apply.

Read (safe-read)

Operational writes (ops-write)

Admin writes (admin)

Environment variables

Security

• Default profile is safe-read — writes require an explicit env-var opt-in.

• Every write tool defaults to dryRun: true. Apply mode performs a GET-merge-PATCH and re-reads to surface any controller-side overrides (mutually-exclusive settings, silent rejections).

• Credentials are read only from env vars, never from tool arguments, never logged, never returned in tool output. The access token is registered with the logger so any accidental serialisation is masked.

• Don't expose this server over a network in its current form. HTTP transport is not yet implemented and there is no authentication layer. Run it locally as documented in Quick start above.

Development

npm install
npm run build         # tsc
npm run typecheck     # tsc --noEmit
npm run lint          # biome check
npm run test          # vitest

docs/openapi/ holds the captured TP-Link Omada Open API v1 spec (omada-open-api-v1-spec.json, OpenAPI 3.0.1) and an endpoint-map.md documenting which Open API endpoint backs each MCP tool.

Prior art

Three other Omada MCP projects were consulted as references during the design (all MIT):

• MiguelTVMS/tplink-omada-mcp

• realtydev/omada-mcp

• gaspareduard/Omada-mcp

omada-mcp is independent code; the differentiator is the security-first capability tiers, the dry-run framework with post-apply re-read, and first-class write coverage of SSID / AP-radio / site-roaming config.

License

MIT — see LICENSE.