Omada MCP

Name: Omada MCP
Author: Alex Gibson

Reads and changes a TP-Link Omada SDN controller's sites, devices, clients, VLANs, firewall and Wi-Fi

By Alex Gibson (individual) TypeScript Local · stdio DevOps and monitoring

GitHub Website

12 popularity score ★ 9

Connect your client

Local (container)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs OMADA_BASE_URL, OMADA_OMADAC_ID, OMADA_CLIENT_ID, OMADA_CLIENT_SECRET. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add omada -e OMADA_BASE_URL=<OMADA_BASE_URL> -e OMADA_OMADAC_ID=<OMADA_OMADAC_ID> -e OMADA_CLIENT_ID=<OMADA_CLIENT_ID> -e OMADA_CLIENT_SECRET=<OMADA_CLIENT_SECRET> -- docker run -i --rm -e OMADA_BASE_URL -e OMADA_CLIENT_ID -e OMADA_CLIENT_SECRET -e OMADA_OMADAC_ID ghcr.io/realtydev/omada-mcp:latest

Claude Desktopclaude_desktop_config.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",
        "ghcr.io/realtydev/omada-mcp:latest"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

Cursor~/.cursor/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",
        "ghcr.io/realtydev/omada-mcp:latest"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "omada": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OMADA_BASE_URL",
        "-e",
        "OMADA_CLIENT_ID",
        "-e",
        "OMADA_CLIENT_SECRET",
        "-e",
        "OMADA_OMADAC_ID",
        "ghcr.io/realtydev/omada-mcp:latest"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.omada]
command = "docker"
args = ["run", "-i", "--rm", "-e", "OMADA_BASE_URL", "-e", "OMADA_CLIENT_ID", "-e", "OMADA_CLIENT_SECRET", "-e", "OMADA_OMADAC_ID", "ghcr.io/realtydev/omada-mcp:latest"]

[mcp_servers.omada.env]
OMADA_BASE_URL = "<OMADA_BASE_URL>"
OMADA_OMADAC_ID = "<OMADA_OMADAC_ID>"
OMADA_CLIENT_ID = "<OMADA_CLIENT_ID>"
OMADA_CLIENT_SECRET = "<OMADA_CLIENT_SECRET>"

Gemini CLITerminal

gemini mcp add --scope user -e OMADA_BASE_URL=<OMADA_BASE_URL> -e OMADA_OMADAC_ID=<OMADA_OMADAC_ID> -e OMADA_CLIENT_ID=<OMADA_CLIENT_ID> -e OMADA_CLIENT_SECRET=<OMADA_CLIENT_SECRET> omada docker -- run -i --rm -e OMADA_BASE_URL -e OMADA_CLIENT_ID -e OMADA_CLIENT_SECRET -e OMADA_OMADAC_ID ghcr.io/realtydev/omada-mcp:latest

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs OMADA_BASE_URL, OMADA_OMADAC_ID, OMADA_CLIENT_ID, OMADA_CLIENT_SECRET. Replace each <NAME> with your value.

FirstTerminal

git clone https://github.com/realtydev/omada-mcp.git && cd omada-mcp
corepack enable && yarn install && yarn build

Claude CodeTerminal

claude mcp add omada -e OMADA_BASE_URL=<OMADA_BASE_URL> -e OMADA_OMADAC_ID=<OMADA_OMADAC_ID> -e OMADA_CLIENT_ID=<OMADA_CLIENT_ID> -e OMADA_CLIENT_SECRET=<OMADA_CLIENT_SECRET> -- node '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "omada": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"
      ],
      "env": {
        "OMADA_BASE_URL": "<OMADA_BASE_URL>",
        "OMADA_OMADAC_ID": "<OMADA_OMADAC_ID>",
        "OMADA_CLIENT_ID": "<OMADA_CLIENT_ID>",
        "OMADA_CLIENT_SECRET": "<OMADA_CLIENT_SECRET>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.omada]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/dist/index.js"]

[mcp_servers.omada.env]
OMADA_BASE_URL = "<OMADA_BASE_URL>"
OMADA_OMADAC_ID = "<OMADA_OMADAC_ID>"
OMADA_CLIENT_ID = "<OMADA_CLIENT_ID>"
OMADA_CLIENT_SECRET = "<OMADA_CLIENT_SECRET>"

Gemini CLITerminal

gemini mcp add --scope user -e OMADA_BASE_URL=<OMADA_BASE_URL> -e OMADA_OMADAC_ID=<OMADA_OMADAC_ID> -e OMADA_CLIENT_ID=<OMADA_CLIENT_ID> -e OMADA_CLIENT_SECRET=<OMADA_CLIENT_SECRET> omada node -- '<ABSOLUTE_PATH_TO_CLONE>/dist/index.js'

Settings 12

`OMADA_BASE_URL`	Required: Address of the Omada controller, e.g. https://omada.local:8043.
`OMADA_OMADAC_ID`	Required: The controller ID (omadacId).
`OMADA_CLIENT_ID`	Required: Open API client ID; needed in the default oauth mode.
`OMADA_CLIENT_SECRET`	Required: Open API client secret; needed in the default oauth mode.
`OMADA_AUTH_MODE`	Optional: oauth (default) or web for Fusion web-session login.
`OMADA_WEB_USERNAME`	Optional: Web UI username; needed in web mode and for route, port forward and IP group tools.
`OMADA_WEB_PASSWORD`	Optional: Web UI password, paired with OMADA_WEB_USERNAME.
`OMADA_SITE_ID`	Optional: Default site ID for tools.
`OMADA_STRICT_SSL`	Optional: Verify the controller's TLS certificate; true by default, false for self-signed.
`OMADA_TIMEOUT`	Optional: Request timeout in ms, 30000 by default.
`MCP_SERVER_USE_HTTP`	Optional: true to serve HTTP instead of stdio.
`MCP_HTTP_BIND_ADDR`	Optional: HTTP bind address, 127.0.0.1 by default.

In a container, a setting goes in with -e NAME=value after docker run.

What it does

Omada MCP connects an MCP client to a TP-Link Omada SDN controller so an assistant can inspect and reconfigure a network managed by it: sites, gateways, switches, access points, connected clients, LAN networks and VLANs, firewall rules and ACLs, SSIDs, static routes, port forwarding and WAN ports. It is a community project maintained by realtydev, which grew out of MiguelTVMS's tplink-omada-mcp; it is not published by TP-Link.

It has 78 tools at v0.6.1 (counted in src/tools/index.ts): 34 that read state, history, alerts, logs and statistics, and the rest that create, change or delete configuration, reboot or adopt devices, block clients, start firmware upgrades and run cable tests. A genericApiCall tool can reach any Open API endpoint the other tools do not cover. Most tools go through Omada's official Open API; routes, port forwarding writes and IP groups go through the controller's internal web UI API, which needs a web UI username and password as well.

It runs over stdio by default, or as a Streamable HTTP or SSE server with health checks, CORS settings and optional ngrok tunnelling. The repository also ships a separate optional WAN failover guard process, started with yarn wan-guard, which disconnects the primary WAN port when a cable modem hands out a private fallback lease; it is off and in dry-run mode unless enabled.

What it needs

Runtime	DockerorNode.js 24+

A TP-Link Omada SDN controller you can reach over the network, its controller ID (omadacId), and either Open API client credentials created in the controller (default oauth mode) or, for Fusion gateways without them, a web UI username and password (OMADA_AUTH_MODE=web). Docker for the published image ghcr.io/realtydev/omada-mcp, or Node 24 with Yarn 4 through Corepack to build from source. Route, port forwarding and IP group tools also need OMADA_WEB_USERNAME and OMADA_WEB_PASSWORD.

Limits

Only works with TP-Link Omada controllers. The internal web UI API used for routes and port forwarding is not a documented TP-Link interface. Dry runs exist only on setApRadio and setLogNotifications; other writes apply straight to the live network. The README lists silent as a value for MCP_SERVER_LOG_LEVEL, but src/config.ts at v0.6.1 accepts only debug, info, warn and error, so silent fails start-up validation. The HTTP endpoint has no authentication of its own. Requests time out after 30000 ms unless OMADA_TIMEOUT is set.

Who it suits

Suits people who run an Omada network, at home or for a small business, and want an assistant to diagnose Wi-Fi, clients and WAN problems and make changes, with Docker or Node available on a machine that can reach the controller. Because many tools write to live network settings, anyone who only wants reporting should give it an Open API app with a viewer role. kaviththiranga's omada-mcp-server, which we also list, is a separate Omada server that takes its pinned OpenAPI export from this repository; this one has hand-written tools plus the web UI API for routes and port forwarding.

Tools 60 of 78

listSites: Lists every site on the controller
listDevices: Lists the devices at one site
listClients: Lists the clients connected at one site
getDevice: Shows the details of one device
getGatewayWanStatus: Live WAN port state: link, internet, IPv4 lease, DNS, latency, loss
getApRadios: Shows an access point's radio settings and retry and drop counts
getClientHistory: Shows a client's sessions over a time range, with roams if asked
getClient: Shows the details of one client
searchDevices: Finds devices across all sites
listDevicesStats: Device statistics with paging and filters
listMostActiveClients: Clients ranked by traffic
listClientsActivity: Client activity as a time series
getThreatList: Security threats found, with filters
getInternetInfo: Shows the internet and WAN setup
getPortForwardingStatus: Lists port forwarding rules, user and UPnP
getLanNetworkList: Lists LAN networks and their VLANs
getSsidList: Lists the SSIDs in a WLAN group
getSsidDetail: Shows the full settings of one SSID
getFirewallSetting: Shows firewall rules and policies
getIpsSetting: Shows whether IDS/IPS is on at a gateway, its mode and level
getFirmwareDetails: Shows firmware information for a device
listAlerts: Site alerts by page, filtered by module or resolved state
listEvents: Site events by page, filtered by module or event key
listFirewallAcls: Lists firewall ACL rules
listIpGroups: Lists IP groups used by ACLs; needs web UI login
listRoutes: Lists static routes; needs web UI login
getSwitch: Shows a switch with per-port status, profile and PoE
getSwitchNetworks: Shows a switch's VLAN trunking
createLanNetwork: Adds a LAN network with VLAN, subnet, DHCP and DNS
updateLanNetwork: Changes a LAN network
deleteLanNetwork: Removes a LAN network
updateFirewallSetting: Changes firewall settings
setIpsSetting: Turns IDS/IPS on or off and sets its mode and level
createFirewallAcl: Adds a firewall ACL rule
updateFirewallAcl: Changes a firewall ACL rule
deleteFirewallAcl: Removes a firewall ACL rule
updateSsid: Changes an SSID's name, band, security, VLAN or key
setSsidEnable: Turns an SSID on or off across the network
updateSwitchPort: Changes a switch port's profile, PoE, speed or STP
updateClient: Changes a client's settings
setSwitchNetworks: Sets a switch's VLAN trunking
createRoute: Adds a static route; web UI API
updateRoute: Changes a static route; web UI API
deleteRoute: Removes a static route; web UI API
createPortForward: Adds a port forwarding rule; web UI API
updatePortForward: Changes a port forwarding rule; web UI API
deletePortForward: Removes a port forwarding rule; web UI API
updateWanPortSetting: Changes a gateway WAN port's IPv4, IPv6 or MAC settings
setSwitchPortStatus: Turns one port on or off
startCableTest: Runs a cable test on a switch
rebootDevice: Restarts a device
adoptDevice: Adopts a device into the controller
blockClient: Blocks a client
reconnectClient: Forces a client to reconnect
setLogNotifications: Turns alert and event notification types on or off; dry run
setApRadio: Changes one AP radio band and checks it applied; dry run
startFirmwareUpgrade: Starts a firmware upgrade
setGatewayWanConnect: Connects or disconnects a gateway WAN port
genericApiCall: Calls any Omada Open API endpoint directly
getServerInfo: Reports the version and git commit the server was built from

Popularity

12 popularity score

★ 9

GitHub stars	9	12 points

Measured 2026-11-07. How the score works.

Where it is published

Code	realtydev/omada-mcp ★ 9
Container	ghcr.io/realtydev/omada-mcp

What it can reach

Runs	On your machine
Reaches	The internet, Your account at a service
Changes things	Yes: it can write, send, create or delete
Sign-in	An API key or token
Licence	MIT (GitHub)
Latest version	0.6.1 GitHub release, 2026-09-25
Last code change	2026-09-25

Talks to your Omada controller over its Open API and, when web UI credentials are given, its internal web UI API; the code runs on your machine or in your container. Write tools can change VLANs, firewall rules and ACLs, SSIDs and keys, routes, port forwards and WAN settings, reboot devices, block clients and start firmware upgrades, and genericApiCall can reach any Open API endpoint. Writes carry the destructiveHint annotation. Signs in with Open API client credentials or a web UI username and password held in environment variables. The README advises a viewer-role Open API app for read-only use, keeping OMADA_STRICT_SSL on, and leaving the unauthenticated HTTP endpoint bound to 127.0.0.1 (its default).

Over time

GitHub stars 9 +2 (+29 %)

14 Oct 20267 Nov 2026

Popularity score 12 +1 (+11 %)

1211

14 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Omada MCP on EveryMCPServer](https://everymcpserver.com/badge/omada-mcp-realtydev.svg)](https://everymcpserver.com/servers/omada-mcp-realtydev)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 60 of 78

Similar servers

omada-mcp

TP-Link Omada MCP server

MikroTik MCP

Linux MCP Server

Opik MCP Server

homebutler