Omada Mcp

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 ``

1. Edit your Claude Desktop MCP config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. 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" ] } } } ``

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

Option 2: Run the container directly

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

Option 3: Run locally for development

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:

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
• Source: gaspareduard/Omada-mcp
• License: MIT

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