# Omada Mcp

> Security-first MCP server for TP-Link Omada, with a stdio-first runtime, capability-gated tools, and OpenAPI-based network automation.

- **Type:** MCP server
- **Install:** `agentstack add mcp-gaspareduard-omada-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gaspareduard](https://agentstack.voostack.com/s/gaspareduard)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gaspareduard](https://github.com/gaspareduard)
- **Source:** https://github.com/gaspareduard/Omada-mcp

## Install

```sh
agentstack add mcp-gaspareduard-omada-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Safe Omada MCP

[](https://github.com/gaspareduard/Omada-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/safe-omada-mcp)
[](./LICENSE)
[](https://nodejs.org)

Security-focused MCP server for TP-Link Omada Open API workflows.

## At a Glance

- Production-safe baseline uses `stdio`
- Omada credentials are environment-only
- Capability profiles and category gating control what tools are exposed
- HTTP remains in the codebase only as an explicitly unsafe, lab-only path
- Validated against live Omada Controller 6.x environments and designed around the documented 5.x/6.x Open API surface

## Quick Start

### Option 1: Use with Claude Desktop via Docker

1. Pull or build an image:

   ```bash
   docker pull ghcr.io/gaspareduard/omada-mcp:latest
   ```

   If you do not publish an image yet, build locally instead:

   ```bash
   npm run docker:build
   ```

2. Edit your Claude Desktop MCP config:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

3. Add the server entry:

   ```json
   {
     "mcpServers": {
       "safe-omada": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "OMADA_BASE_URL=https://your-omada-controller.local",
           "-e", "OMADA_CLIENT_ID=your-client-id",
           "-e", "OMADA_CLIENT_SECRET=your-client-secret",
           "-e", "OMADA_OMADAC_ID=your-omadac-id",
           "-e", "OMADA_SITE_ID=your-site-id",
           "-e", "OMADA_STRICT_SSL=true",
           "ghcr.io/gaspareduard/omada-mcp:latest"
         ]
       }
     }
   }
   ```

4. Restart Claude Desktop and verify the server by listing sites or devices.

### Option 2: Run the container directly

```bash
docker run --rm -it \
  --env-file .env \
  ghcr.io/gaspareduard/omada-mcp:latest
```

### Option 3: Run locally for development

```bash
npm install
npm run build
npm start
```

## Configuration

The server reads configuration from environment variables. See `.env.example` for the complete reference.

### Required Omada Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `OMADA_BASE_URL` | Yes | - | Base URL of the Omada controller |
| `OMADA_CLIENT_ID` | Yes | - | OAuth client ID from Omada Platform Integration |
| `OMADA_CLIENT_SECRET` | Yes | - | OAuth client secret |
| `OMADA_OMADAC_ID` | Yes | - | Omada controller ID (`omadacId`) |
| `OMADA_SITE_ID` | No | - | Optional default site ID |
| `OMADA_STRICT_SSL` | No | `true` | Enforce TLS certificate validation |
| `OMADA_TIMEOUT` | No | `30000` | HTTP timeout in milliseconds |

### Capability and Logging

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `OMADA_CAPABILITY_PROFILE` | No | `safe-read` | Built-in profile: `safe-read`, `ops-write`, `admin`, `compatibility` |
| `OMADA_TOOL_CATEGORIES` | No | profile default | Explicit category override |
| `MCP_SERVER_LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error`, `silent` |
| `MCP_SERVER_LOG_FORMAT` | No | `plain` | `plain`, `json`, or `gcp-json` |

### Capability Profiles

| Profile | Intended use |
| --- | --- |
| `safe-read` | Default read-only operational visibility |
| `ops-write` | Limited operational write actions |
| `admin` | Full documented tool surface, including admin mutations |
| `compatibility` | Reserved for future controller-specific fallback modules |

### Destructive Tool Confirmation Gate

The four restore tools (`restoreController`, `restoreControllerFromFileServer`, `restoreSites`, `restoreSitesFromFileServer`) enforce a two-step confirmation: without `confirmDangerous: true` the tool returns a warning explaining the action is irreversible and that a force recovery or factory reset may be required if something goes wrong.

**Scope of this protection:** this gate is effective in conversational AI sessions where the warning is surfaced to a human who then decides whether to confirm. It does not prevent a fully autonomous agent from passing `confirmDangerous: true` programmatically without human review.

**True human-in-the-loop enforcement requires one or both of:**
- **MCP client approval mode** — Claude Desktop and compatible MCP hosts can be configured to require explicit human approval before any tool call executes. This is the only reliable technical gate against autonomous execution.
- **Capability profile restriction** — the restore tools require `maintenance:rw`, which is only granted under `ops-write` or `admin`. Keeping the deployment on the default `safe-read` profile blocks all restore tools entirely.

### Optional HTTP Lab Mode

HTTP is **not** part of the supported production baseline.

It only starts when both of these are set:
- `MCP_SERVER_USE_HTTP=true`
- `MCP_UNSAFE_ENABLE_HTTP=true`

Use it only for local lab/debug scenarios.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `MCP_SERVER_USE_HTTP` | No | `false` | Legacy lab-only switch |
| `MCP_UNSAFE_ENABLE_HTTP` | No | `false` | Explicit acknowledgement required |
| `MCP_HTTP_PORT` | No | `3000` | HTTP port |
| `MCP_HTTP_BIND_ADDR` | No | `127.0.0.1` | Loopback bind address only (`127.0.0.1` or `::1`) |
| `MCP_HTTP_PATH` | No | `/mcp` | MCP endpoint path |
| `MCP_HTTP_ENABLE_HEALTHCHECK` | No | `true` | Enable health check |
| `MCP_HTTP_HEALTHCHECK_PATH` | No | `/healthz` | Health check path |
| `MCP_HTTP_ALLOW_CORS` | No | `true` | Enable CORS |
| `MCP_HTTP_ALLOWED_ORIGINS` | No | `127.0.0.1, localhost` | Allowed origins |
| `MCP_HTTP_NGROK_ENABLED` | No | `false` | Legacy placeholder; disabled in safe baseline |
| `MCP_HTTP_NGROK_AUTH_TOKEN` | No | - | Legacy placeholder |

## Development and Validation

### Common Commands

| Task | Command |
| --- | --- |
| Run dev server | `npm run dev` |
| Build | `npm run build` |
| Lint + type-check | `npm run check` |
| Unit tests | `npm test` |
| Coverage gates | `npm run test:coverage` |
| Symlink integrity | `npm run symlinks:check` |
| README/tool sync | `node scripts/check-readme-sync.mjs` |
| Tool/test mapping | `node scripts/check-tool-tests.mjs` |

### Inspector

Use the MCP Inspector when you want to test the built server interactively:

```bash
npm run inspector
npm run inspector:build
```

## Project Notes

- The safe baseline is `stdio` first.
- HTTP remains a legacy, explicitly unsafe lab path.
- The repo includes `docs/openapi/` as the implementation reference for Omada endpoints.
- README tool tables below are kept in sync with the registered MCP tools.

## Tools

### Site & Client

| Tool                        | Description                                                                  |
| --------------------------- | ---------------------------------------------------------------------------- |
| `listSites` | Lists all sites configured on the controller. |
| `getSiteCapacity` | Get site capacity settings including maximum device and client counts. |
| `getSiteDetail` | Get detailed information about a site, including name, region, timezone, and configuration. |
| `getSiteDeviceAccount` | Get device account settings for a site. |
| `getSiteNtpStatus` | Get NTP server status and configuration for a site. |
| `getSiteRememberSetting` | Get the remember device setting for a site. |
| `getSiteSpecification` | Get site specification including device limits and feature capabilities. |
| `getSiteUrl` | Get the URL associated with a site for OpenAPI access. |
| `getSiteTemplateConfig` | Get configuration settings for a site template. Requires `siteTemplateId`. |
| `getSiteTemplateDetail` | Get detailed information about a site template. Requires `siteTemplateId`. |
| `getSiteTemplateList` | List all site templates configured on the controller. |
| `listClients` | Lists active client devices for a site. |
| `getClient` | [DEPRECATED] Use `listClients` instead. When you have a client MAC, `getClientDetail` is also available. This tool filters the site client list in-process. |
| `listMostActiveClients` | Gets the most active clients sorted by traffic usage. |
| `listClientsActivity` | Gets client activity statistics over time. |
| `listClientsPastConnections`| Gets past connection history for clients.                                    |
| `setClientRateLimit` | Sets custom bandwidth limits (download/upload) for a specific client. |
| `setClientRateLimitProfile` | Applies a predefined rate limit profile to a specific client.                |
| `disableClientRateLimit` | Disables bandwidth rate limiting for a specific client. |
| `blockClient` | Blocks a client from network access with an auditable mutation summary. |
| `unblockClient` | Restores a blocked client to network access with an auditable mutation summary. |
| `reconnectClient` | Forces a client to reconnect with an auditable mutation summary. |
| `rebootDevice` | Reboots a managed device with an auditable mutation summary. |
| `setDeviceLed` | Changes a device LED state with an auditable mutation summary. |
### Device

| Tool                    | Description                                                                       |
| ----------------------- | --------------------------------------------------------------------------------- |
| `listDevices` | Lists provisioned devices for a given site. |
| `getDevice` | [DEPRECATED] Use `listDevices` instead and filter results client-side. This tool filters the site device list in-process; there is no dedicated device-detail endpoint. |
| `searchDevices` | Searches for devices globally across all sites the user has access to. |
| `listDevicesStats` | Queries statistics for global adopted devices with pagination and filtering. |
| `getSwitchStackDetail` | Retrieves detailed configuration and status for a switch stack. |
| `getSwitchDetail` | Fetches detailed configuration and status for a specific switch. |
| `getGatewayDetail` | Fetches detailed configuration and status for a specific gateway. |
| `getGatewayWanStatus` | Gets WAN port status for a specific gateway. |
| `getGatewayLanStatus` | Gets LAN port status for a specific gateway. |
| `getGatewayPorts` | Gets port information for a specific gateway. |
| `getApDetail` | Fetches detailed configuration and status for a specific access point. |
| `getApRadios` | Gets radio information for a specific access point. |
| `getStackPorts` | Gets port information for a switch stack. |
| `listPendingDevices` | Lists devices pending adoption in a site. |
| `getAllDeviceBySite` | Gets all devices in a site including offline and disconnected devices. |
| `getFirmwareInfo` | Gets the latest available firmware info for a device. Use `listDevices` for MACs. |
| `getGridAutoCheckUpgrade` | Gets the auto-check firmware upgrade plan list (paginated).                     |
| `listSwitchNetworks` | Lists VLAN network assignments for a switch (paginated). Requires `switchMac`. |
| `getSwitchGeneralConfig` | Gets general configuration for a switch. Requires `switchMac`.                  |
| `getCableTestLogs` | Gets cable test history for a switch. Requires `switchMac`. |
| `getCableTestFullResults` | Gets full per-port cable diagnostics for a switch. Requires `switchMac`.        |
| `getOswStackLagList` | Gets Link Aggregation Group (LAG) list for a switch stack. Requires `stackId`. |
| `getStackNetworkList` | Gets VLAN network list for a switch stack (paginated). Requires `stackId`. |
| `getApUplinkConfig` | Gets uplink configuration for an AP (wired/mesh mode). Requires `apMac`. |
| `getRadiosConfig` | Gets per-radio configuration for an AP (channel, power, width). Requires `apMac`. |
| `getApVlanConfig` | Get VLAN configuration for an access point, including management VLAN and per-SSID VLAN tagging settings. |
| `getMeshStatistics` | Gets mesh link statistics for an AP. Requires `apMac`. |
| `getRFScanResult` | Gets last RF scan results for an AP. Requires `apMac`. |
| `getSpeedTestResults` | Gets last speed test results for an AP. Requires `apMac`. |
| `getApSnmpConfig` | Gets SNMP configuration for an AP. Requires `apMac`. |
| `getApLldpConfig` | Gets LLDP configuration for an AP. Requires `apMac`. |
| `getApGeneralConfig` | Gets general configuration for an AP (name, LED, country). Requires `apMac`. |
| `getUplinkWiredDetail` | Get wired uplink detail for an access point: uplink switch, port number, link speed, and PoE status. |
| `getDownlinkWiredDevices` | Gets wired downlink devices on an AP's LAN ports. Requires `apMac`.            |
| `getFirmwareUpgradePlan` | Get the firmware upgrade plan list for devices managed by the controller. |
| `getUpgradeLogs` | Get firmware upgrade logs showing the history of upgrade operations performed on devices. |
| `getDeviceTagList` | Get the list of device tags defined in a site. |
| `getApQosConfig` | Get QoS configuration for a specific access point. Requires `apMac`. |
| `getApIpv6Config` | Get IPv6 configuration for a specific access point. Requires `apMac`. |
| `getSitesApsIpSetting` | Get IP settings for an AP. Requires `apMac`. |
| `getSitesApsChannelLimit` | Get channel limit configuration for an AP. Requires `apMac`. |
| `getSitesApsAvailableChannel` | Get list of available channels for an AP. Requires `apMac`. |
| `getSitesApsLoadBalance` | Get load balance configuration for an AP. Requires `apMac`. |
| `getSitesApsOfdma` | Get OFDMA configuration for an AP. Requires `apMac`. |
| `getSitesApsPowerSaving` | Get power saving configuration for an AP. Requires `apMac`. |
| `setApPowerSaving` | Updates AP power saving configuration with support checks and dry-run preview. Requires `apMac`. |
| `setApChannelLimit` | Updates AP channel-limit configuration with support checks and dry-run preview. Requires `apMac`. |
| `setApConfig` | Updates documented AP configuration families with dry-run preview. Covers AP general, IP, IPv6, QoS, radio, service, load-balance, OFDMA, trunk, bridge, WLAN group, port, channel, AFC, and antenna settings. Setter-only families return planned payloads and an explicit warning when controller readback is unavailable. Requires `apMac`. |
| `getSitesApsTrunkSetting` | Get trunk port setting for an AP. Requires `apMac`. |
| `getSitesApsBridge` | Get bridge configuration for an AP. Requires `apMac`. |
| `listSitesApsPorts` | List ports for an AP. Requires `apMac`. |
| `getSitesSwitchesEs` | Get ES switch details. Requires `switchMac`. |
| `getSitesSwitchesEsGeneralConfig` | Get ES switch general configuration. Requires `switchMac`. |
| `listSitesCableTestSwitchesPorts` | List cable test port info for a switch. Requires `switchMac`. |
| `listSitesCableTestSwitchesIncrementResults` | Get incremental cable test results for a switch. Requires `switchMac`. |
| `getUpgradeOverviewCritical` | Get the number of critical models available for upgrade. |
| `getUpgradeOverviewTryBeta` | Get the current status of the try-beta firmware upgrade switch. |
| `listUpgradeFirmwares` | List available firmware packages for upgrade (paginated). |
| `listUpgradeOverviewFirmwares` | List firmware overview for upgradeable devices (paginated). |
| `listSitesStacks` | List switch stacks in a site (paginated). |
| `getSitesDeviceWhiteList` | Get the device adoption whitelist for a site (paginated). |
| `getSitesGatewaysGeneralConfig` | Get general configuration for a gateway. Requires `gatewayMac`. |
| `getSitesGatewaysPin` | Get PIN information for a gateway. Requires `gatewayMac`. |
| `getSitesGatewaysSimCardUsed` | Get SIM card usage info for a gateway. Requires `gatewayMac`. |
| `getSitesHealthGatewaysWansDetails` | Get gateway WAN health details. Requires `gatewayMac`. |
| `setGatewayConfig` | Updates documented gateway configuration families with dry-run preview. Covers general, services, advanced, radios, WLAN, and port settings. Setter-only families return planned payloads and an explicit warning when controller readback is unavailable. Requires `gatewayMac`. |

### Network

| Tool

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gaspareduard](https://github.com/gaspareduard)
- **Source:** [gaspareduard/Omada-mcp](https://github.com/gaspareduard/Omada-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gaspareduard-omada-mcp
- Seller: https://agentstack.voostack.com/s/gaspareduard
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.