Which integrations are available for this server?

Provides tools for interacting with the TP-Link Omada SDN Controller, enabling AI assistants to read and safely modify Omada network settings including sites, devices, clients, SSIDs, site settings, events, logs, and perform operations like reboot, block/unblock client, rate limit, LED control, and more.

How do I use omada-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@omada-mcp list all sites" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

omada-mcp

by dfla-me

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Local

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.

Related MCP server: NetBox Read/Write MCP Server

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:

Push this repo to GitHub under your own account/org (e.g. your-name/omada-mcp).
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).
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`)

Tool	Purpose
`list_sites`	List sites on the controller.
`list_devices`	APs / switches / gateway at a site, with status & firmware.
`get_device`	Per-device detail; for APs, also per-band radio config.
`get_ap_radios`	Per-band radio settings on one AP.
`list_clients`	Connected clients with SSID, AP, RSSI, traffic. Summary counts.
`get_client`	Full client detail.
`list_ssids`	SSIDs grouped by WLAN group.
`get_ssid`	Full SSID configuration.
`get_site_settings`	Aggregate roaming + band-steering + mesh.
`list_events`	Site event log within a time window.
`list_logs`	Site alert log (with `resolved` filter).

Operational writes (`ops-write`)

Tool	Purpose
`reboot_device`	Reboot one AP / switch / gateway.
`block_client` / `unblock_client`	Block / allow a client by MAC.
`reconnect_client`	Force a client to re-associate.
`set_client_rate_limit`	Per-client up / down bandwidth limit.
`set_site_led`	Site-wide LED on / off.

Admin writes (`admin`)

Tool	Purpose
`update_site_roaming`	Fast roaming, AI roaming, force-disassociation, non-stick.
`update_band_steering`	Site band-steering mode.
`update_ssid`	Modify SSID basic config (name, band, broadcast, 802.11r, PMF, VLAN).
`update_ap_radio`	Per-AP per-band: channel, width, Tx power, radio enable.

Environment variables

Variable	Required	Default	Notes
`OMADA_BASE_URL`	yes	—	Controller URL, no trailing slash.
`OMADA_CLIENT_ID`	yes	—	From the Open API app.
`OMADA_CLIENT_SECRET`	yes	—	From the Open API app. Never logged.
`OMADA_OMADAC_ID`	yes	—	Controller ID.
`OMADA_SITE_ID`	no	—	Default site; otherwise tools need `siteId`.
`OMADA_VERIFY_TLS`	no	`true`	`false` for self-signed.
`OMADA_TIMEOUT_MS`	no	`30000`	HTTP timeout.
`OMADA_CAPABILITY_PROFILE`	no	`safe-read`	`safe-read` / `ops-write` / `admin`.
`MCP_TRANSPORT`	no	`stdio`	`stdio` only; setting `http` throws today.
`MCP_HTTP_ENABLE`	no	`false`	Reserved for the future HTTP transport.
`MCP_HTTP_BIND`	no	`127.0.0.1`	Loopback bind when HTTP lands.
`MCP_HTTP_PORT`	no	`3000`
`LOG_LEVEL`	no	`info`	`debug` / `info` / `warn` / `error`.
`OMADA_DOTENV_PATH`	no	—	Explicit override path to a `.env` file. Useful when the MCP client launches the server without a predictable `cwd`.

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):

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.

Available Tools

11 tools

get_ap_radiosGet AP radio configA

Read-only

Per-band radio configuration for one AP: channel, channel width, Tx power and Tx-power level for 2.4/5/6 GHz. Use list_devices to find the AP MAC.

ParametersJSON Schema

Name	Required	Description	Default
`apMac`	Yes	AP MAC, e.g. 'A8-29-48-C1-BB-C0'.
`siteId`	No	Override the default site.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already set readOnlyHint=true and openWorldHint=true. The description adds value by specifying exactly what configuration fields are returned per band, enhancing transparency without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Purpose is front-loaded, usage hint follows. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 parameters and no output schema, the description adequately covers purpose and provides a usage hint. It could mention output format, but given openWorldHint, it's acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description adds a usage hint for apMac but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves per-band radio configuration for one AP, listing specific fields (channel, channel width, Tx power, Tx-power level) and bands (2.4/5/6 GHz). It distinguishes from siblings by referencing list_devices for finding AP MAC.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use list_devices to find the AP MAC', providing a clear prerequisite and linking to a sibling tool. It does not include when-not or alternatives, but the hint is actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_clientGet client detailA

Read-only

Get full detail for one client by MAC: connection (SSID, AP, channel, RSSI, SNR, rates), addressing, traffic, uptime and lifecycle.

ParametersJSON Schema

Name	Required	Description	Default
`clientMac`	Yes	Client MAC, e.g. '5C-1B-F4-7C-25-C9'.
`siteId`	No	Override the default site.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and openWorldHint, and the description adds valuable context about the return content (SSID, AP, channel, etc.), going beyond what annotations provide. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence that front-loads the core purpose and lists key attributes. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple get operation, annotations, and fully described parameters, the description covers all needed context, including a breakdown of what the detail includes, despite the lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters (clientMac, siteId) have descriptions in the schema, and the tool description does not add further meaning. With 100% schema coverage, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Get full detail for one client by MAC' and enumerates the specific details (connection, addressing, traffic, etc.), clearly distinguishing it from sibling tools like list_clients.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for a single client given a MAC address but does not explicitly contrast with list_clients or provide when-not guidance. It is adequate but lacks explicit alternative direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_deviceGet device detailA

Read-only

Get detail for one device by MAC. For APs, also includes per-band radio config (channel, width, Tx power). Use list_devices to find MACs.

ParametersJSON Schema

Name	Required	Description	Default
`deviceMac`	Yes	MAC, e.g. 'A8-29-48-C1-BB-C0'.
`siteId`	No	Override the default site.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint and openWorldHint. Description adds that for APs, the response includes radio config details, which goes beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with core purpose, and efficient. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Sufficient for a simple read tool with annotations. Covers key output for APs and directs to sibling for finding MACs. Could mention error cases, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage with clear parameter descriptions. The tool description does not add additional parameter details beyond the schema, but provides context on output behavior for APs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves details for one device by MAC, with specific mention of per-band radio config for APs, distinguishing it from siblings like list_devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly suggests using list_devices to find MACs, providing clear guidance. Does not explicitly list when not to use, but the context of siblings implies appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_site_settingsGet site settingsA

Read-only

Aggregate site-level wireless settings: roaming (fast roaming, AI roaming, force-disassociation, non-stick, 802.11k report), band steering and mesh. Reads three Open API endpoints in parallel.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Override the default site.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint, openWorldHint), the description adds that it reads three Open API endpoints in parallel and lists the specific settings included, enhancing behavioral understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: one listing settings, one adding technical detail. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers the purpose and key settings, but could mention output format or error handling for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter (siteId) described as 'Override the default site.' The description does not add further parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it aggregates site-level wireless settings like roaming, band steering, and mesh, distinguishing it from per-AP or per-SSID siblings such as get_ap_radios or get_ssid.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for site-level aggregate settings, but does not explicitly state when not to use it or name alternatives. It provides clear context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_ssidGet SSID detailA

Read-only

Full SSID configuration. If wlanId is omitted, the tool finds the owning WLAN group automatically via list_ssids.

ParametersJSON Schema

Name	Required	Description
`ssidId`	Yes	SSID id (from list_ssids).
`wlanId`	No	WLAN-group id (auto-discovered if omitted).
`siteId`	No	Override the default site.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and open-world behavior. The description adds contextual transparency by explaining the automatic WLAN group discovery via 'list_ssids', which is a significant behavioral trait beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the purpose ('Full SSID configuration') and then adds the key behavioral nuance about auto-discovery. Every word is informative with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core functionality and key behavioral trait (auto-discovery) adequately. Given the presence of annotations and 100% schema coverage, it provides sufficient context for an agent to decide when to invoke the tool. Minor gap in not describing the output format, but output schema is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The overall description adds minimal new meaning beyond the schema, only reinforcing the auto-discovery aspect for 'wlanId'. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Full SSID configuration' clearly indicating the tool retrieves complete configuration details for a specific SSID. It also distinguishes itself by describing the automatic WLAN group discovery when 'wlanId' is omitted, which differentiates it from a basic get tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implicit usage guidance by explaining the auto-discovery behavior for the 'wlanId' parameter and hints that 'ssidId' comes from 'list_ssids'. However, it does not explicitly state when to use this tool over siblings or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_clientsList clientsA

Read-only

List connected clients (wired + wireless) at a site, with SSID, AP, band, channel, RSSI, Tx/Rx rate and total traffic. Also returns site summary counts.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Override the default site.
`pageSize`	No	Max rows per page (1-1000, default 100).
`page`	No	Page number (default 1).

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=true (open-ended result set). The description adds behavioral context beyond annotations by detailing the returned fields (SSID, AP, etc.) and the inclusion of site summary counts. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences, front-loaded with the tool's purpose. Every word serves a purpose, with no redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated list tool with three optional parameters and no output schema, the description is complete. It enumerates the returned data fields (SSID, AP, band, etc.) and mentions the site summary counts, leaving no significant gaps. Annotations also provide safety and open-world hints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with each parameter already described (siteId, pageSize, page). The description does not add new parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists connected clients (wired + wireless) at a site, specifying the action ('list') and the resource ('clients'). It differentiates from siblings like 'get_client' which retrieves a single client, and 'list_devices' which lists devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by stating 'at a site', informing the agent that site context is needed. It does not explicitly list when not to use or mention alternatives, but the context is clear for a list endpoint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_devicesList devicesA

Read-only

List APs, switches and gateways at a site, with model, IP, status, firmware version and last-seen timestamp.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Override the default site (OMADA_SITE_ID).

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description does not need to repeat those. It adds value by specifying the fields returned. However, it does not mention any potential pagination or limits, which would be useful for a list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose and output details without any fluff. It is front-loaded with the verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple input schema (one optional parameter) and no output schema, the description covers the core functionality well. It lists the output fields, but does not explain what happens if no devices are found or if there are errors. A mention of response format could improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter (siteId) with a description that it overrides the default site. The description does not add additional semantic meaning to the parameter beyond what the schema provides. Schema description coverage is 100%, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'APs, switches and gateways at a site', and also enumerates the fields returned (model, IP, status, firmware version, last-seen timestamp). This distinguishes it from siblings like get_device or get_ap_radios by specifying multiple device types and attributes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for listing multiple devices, but it does not explicitly state when to use it versus alternatives like get_device (for a single device) or get_ap_radios (for AP radios). No usage context or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_eventsList site eventsA

Read-only

Site event log (System / Device / Client events) within a time window. Defaults to the last 24 hours. Returns counts and a sample of entries.

ParametersJSON Schema

Name	Required	Description
`siteId`	No
`hoursAgo`	No	Look-back window in hours (1-168, default 24).
`module`	No	Optionally filter to one module.
`pageSize`	No	Max entries to return (1-100, default 50).
`page`	No

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only (readOnlyHint) and open-world (openWorldHint) behavior. The description adds that it returns counts and a sample of entries, defaults to 24 hours, and allows filtering by module, providing useful context beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that front-load the main purpose, default behavior, and output type. Every word adds value, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core functionality (event types, time window, output) but omits details about siteId (likely required) and pagination (page parameter). Without an output schema, the return structure of the sample is also not described, leaving gaps for a parameter-rich tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 60% (hoursAgo, module, pageSize have descriptions; siteId and page do not). The description adds meaning for module (listing types) and time window, but fails to explain the siteId (likely required but not clarified) and page (pagination) parameters. This under-compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists site events within a time window, specifies the event types (System/Device/Client), and explains what it returns (counts and a sample). This distinguishes it from siblings like list_logs and list_clients.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving event logs within a time window with optional filtering, but it does not explicitly say when to use this over sibling tools like list_logs (which might serve a different purpose). No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_logsList alert logA

Read-only

Site alert log within a time window. Defaults to the last 24 hours. Optionally filter by module or resolved/unresolved.

ParametersJSON Schema

Name	Required	Description
`siteId`	No
`hoursAgo`	No	Look-back window in hours (1-168, default 24).
`module`	No
`resolved`	No	If set, only show resolved (true) or unresolved (false) alerts.
`pageSize`	No
`page`	No

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint and openWorldHint, so the description adds value by noting the default time window and filter options. However, it does not discuss pagination, rate limits, or authentication beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the core purpose and key options. Every sentence contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with readOnly and openWorld annotations, the description adequately covers input defaults and filters. It does not describe output format, but this is acceptable given the lack of output schema and the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 2 of 6 parameters have schema descriptions (33% coverage). The description adds meaning for 'module' and 'resolved' parameters but omits 'siteId', 'pageSize', and 'page'. This partially compensates for low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies it lists site alert logs with a time window, defaults, and optional filters. This clearly distinguishes it from sibling list tools like list_clients, list_devices, list_events, etc., which operate on different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states defaults and optional filters, providing clear context for when to use the tool. While it does not explicitly exclude alternative tools, the name and description make its purpose unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sitesList sitesA

Read-only

List all sites on the Omada controller. Returns each site's id, name, region and time zone — useful as a starting point and to find the siteId that other tools need.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and openWorldHint. Description adds that it returns specific fields (id, name, region, time zone), which is useful beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences with no wasted words. Purpose and guidance front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless listing tool with no output schema, description fully covers what it does, what it returns, and why it's useful. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0 parameters with 100% coverage, so baseline is 3. Description mentions output fields which adds value but does not need to elaborate on param syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List all sites on the Omada controller' with specific output fields (id, name, region, time zone). Distinct from sibling tools like list_clients and list_devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly notes it's 'useful as a starting point' and to find siteId needed by other tools, providing clear when-to-use guidance. Lacks explicit when-not-to-use but context is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ssidsList SSIDsA

Read-only

List all SSIDs at a site, grouped by their WLAN group. Returns wlanId/wlanName and the ssidId/ssidName for each SSID — use those ids with get_ssid for full SSID configuration.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Override the default site.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so description need not emphasize safety. It adds no behavioral traits beyond listing, which is consistent. No superfluous details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose and grouping, second specifies return structure and usage hint. No redundant words, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Explains return format and grouping despite no output schema. Could clarify effect of siteId optionality, but overall sufficient for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter siteId is described in the schema as 'Override the default site.' The description does not add further meaning; schema coverage is 100%, so baseline applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all SSIDs at a site grouped by WLAN group, and specifies return fields. It distinguishes from sibling get_ssid by noting the use of returned ids for full config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicitly provides usage context by advising to use returned ids with get_ssid for full config, indicating this tool is for overview. However, no explicit when-not or alternative comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv0.1.0May 26, 2026
- First observedget_ap_radios
- First observedget_client
- First observedget_device
- First observedget_site_settings
- First observedget_ssid
- First observedlist_clients
- First observedlist_devices
- First observedlist_events
- First observedlist_logs
- First observedlist_sites
- First observedlist_ssids

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Scored 2026-05-26 01:45 across 11 tools

Disambiguation4/5

Most tools target distinct resources or aspects (e.g., clients, devices, events, logs, SSIDs). There is minor overlap between get_device (which includes radio info) and get_ap_radios (which focuses solely on radio configuration), but descriptions differentiate them.

Naming Consistency5/5

All tool names follow a consistent 'verb_noun' pattern in snake_case (get_*, list_*). No mixed conventions or irregular verbs.

Tool Count5/5

With 11 tools covering sites, devices, clients, events, logs, SSIDs, and settings, the count is well-scoped for a monitoring-oriented MCP server. No excessive or trivial tools.

Completeness4/5

The tool set covers core read operations for Omada network management (list, get details, settings). Minor gaps exist: no write operations (create/update/delete) and no advanced features like switch port info or topology, but essential monitoring is covered.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216

Related MCP Servers

Command Executor MCP Server
Shell Access Code Execution Command Line
Sunwood-ai-labs
A
license
B
quality
D
maintenance
A Model Context Protocol server that allows secure execution of pre-approved commands, enabling AI assistants to safely interact with the user's system.
Updated 2 years ago (2024-12-22 05:16 UTC)
1
2
22
ISC
NetBox Read/Write MCP Server
Databases RAG Systems Autonomous Agents
Deployment-Team
A
license
Not graded
quality
Not graded
maintenance
A Model Context Protocol server that provides safe, intelligent read/write access to NetBox instances, designed with safety-first principles for Large Language Model automation.
Updated a year ago (2025-09-19 20:04 UTC)
4
-
safe-omada-mcp
Networking & Infrastructure Observability Security
gaspareduard
A
license
B
quality
F
maintenance
Security-focused MCP server for TP-Link Omada Open API workflows, enabling network management via natural language.
Updated 5 months ago (2026-04-05 12:55 UTC)
87
21
MIT
mcp-omada
Networking & Infrastructure Monitoring
thalisantunes
A
license
Not graded
quality
B
maintenance
Read-only MCP server for TP-Link Omada SDN controllers, enabling querying controller, site, device, and WiFi state.
Updated 2 months ago (2026-07-13 11:57 UTC)
Apache 2.0

omada-mcp

Status — local use only

Quick start

1. Create an Open API client in the controller

2. Configure .env

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

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

Option B — Local Docker build

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

Tool catalog

Read (safe-read)

Operational writes (ops-write)

Admin writes (admin)

Environment variables

Security

Development

Prior art

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

2. Configure `.env`

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

Read (`safe-read`)

Operational writes (`ops-write`)

Admin writes (`admin`)