{"id":50718273,"url":"https://github.com/daniel-k/omada-mcp","last_synced_at":"2026-06-09T21:01:58.420Z","repository":{"id":351582826,"uuid":"1191731629","full_name":"daniel-k/omada-mcp","owner":"daniel-k","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-07T21:25:15.000Z","size":2400,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T23:33:28.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-k.png","metadata":{"files":{"readme":"README.Docker.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T14:32:16.000Z","updated_at":"2026-05-07T21:25:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daniel-k/omada-mcp","commit_stats":null,"previous_names":["daniel-k/omada-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/daniel-k/omada-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-k%2Fomada-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-k%2Fomada-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-k%2Fomada-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-k%2Fomada-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-k","download_url":"https://codeload.github.com/daniel-k/omada-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-k%2Fomada-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34125332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T21:01:57.801Z","updated_at":"2026-06-09T21:01:58.408Z","avatar_url":"https://github.com/daniel-k.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TP-Link Omada MCP Server\n\nA Model Context Protocol (MCP) server that exposes TP-Link Omada controller APIs to AI copilots and automation workflows. This Docker image provides an easy way to run the MCP server with support for both stdio and HTTP transports.\n\n## Quick Start\n\n### Using with Claude Desktop (stdio)\n\n1. **Pull the Docker image**:\n\n   ```bash\n   docker pull jmtvms/tplink-omada-mcp:latest\n   ```\n\n2. **Add the MCP server to Claude Desktop configuration**. Edit your Claude Desktop config file:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n3. **Add the following configuration**:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"tplink-omada\": {\n         \"command\": \"docker\",\n         \"args\": [\n           \"run\",\n           \"-i\",\n           \"--rm\",\n           \"-e\", \"OMADA_BASE_URL=https://your-omada-controller.local\",\n           \"-e\", \"OMADA_CLIENT_ID=your-client-id\",\n           \"-e\", \"OMADA_CLIENT_SECRET=your-client-secret\",\n           \"-e\", \"OMADA_OMADAC_ID=your-omadac-id\",\n           \"-e\", \"OMADA_SITE_ID=your-site-id\",\n           \"-e\", \"OMADA_STRICT_SSL=false\",\n           \"jmtvms/tplink-omada-mcp:latest\"\n         ]\n       }\n     }\n   }\n   ```\n\n   Replace the environment variable values with your actual Omada controller credentials.\n\n4. **Restart Claude Desktop** to load the new MCP server configuration.\n\n5. **Verify the connection** by asking Claude to list your Omada sites or devices.\n\n### Using Docker Containers\n\n#### CLI/stdio Container\n\n```bash\ndocker run -it --rm \\\n  --env-file .env \\\n  jmtvms/tplink-omada-mcp:latest\n```\n\n#### HTTP Server Container\n\n```bash\ndocker run -d \\\n  --env-file .env \\\n  -e MCP_SERVER_USE_HTTP=true \\\n  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \\\n  -p 3000:3000 \\\n  jmtvms/tplink-omada-mcp:latest\n```\n\nThe HTTP server will be available at `http://localhost:3000/mcp` (stream transport) or `http://localhost:3000/sse` (SSE transport).\n\n## Features\n\n- OAuth client-credentials authentication with automatic token refresh\n- Tools for retrieving sites, network devices, and connected clients\n- Generic Omada API invoker for advanced automation scenarios\n- Environment-driven configuration\n- Support for both stdio and HTTP transports\n- Multi-platform support (linux/amd64, linux/arm64)\n\n## Configuration\n\nThe MCP server reads its configuration from environment variables.\n\n### Omada Client Configuration\n\n| Variable              | Required | Default | Description                                                                 |\n| --------------------- | -------- | ------- | --------------------------------------------------------------------------- |\n| `OMADA_BASE_URL`      | Yes      | -       | Base URL of the Omada controller (e.g., `https://omada-controller.local`)   |\n| `OMADA_CLIENT_ID`     | Yes      | -       | OAuth client ID generated under Omada Platform Integration                  |\n| `OMADA_CLIENT_SECRET` | Yes      | -       | OAuth client secret associated with the client ID                           |\n| `OMADA_OMADAC_ID`     | Yes      | -       | Omada controller ID (omadacId) to target                                    |\n| `OMADA_SITE_ID`       | No       | -       | Optional default site ID; if omitted, each MCP call must pass a siteId      |\n| `OMADA_STRICT_SSL`    | No       | `true`  | Enforce strict SSL certificate validation (set to `false` for self-signed)  |\n| `OMADA_TIMEOUT`       | No       | `30000` | HTTP request timeout in milliseconds                                        |\n\n### MCP Generic Server Configuration\n\n| Variable                 | Required | Default | Description                                                                 |\n| ------------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `MCP_SERVER_LOG_LEVEL`   | No       | `info`  | Logging verbosity (`debug`, `info`, `warn`, `error`, `silent`)              |\n| `MCP_SERVER_LOG_FORMAT`  | No       | `plain` | Log output format (`plain`, `json`, or `gcp-json`)                          |\n| `MCP_SERVER_USE_HTTP`    | No       | `false` | Start HTTP server instead of stdio                                          |\n| `MCP_SERVER_STATEFUL`    | No       | `false` | Maintain stateful sessions per client                                       |\n\n### MCP Server HTTP Configuration\n\nThese variables are only used when `MCP_SERVER_USE_HTTP=true`:\n\n| Variable                       | Required | Default                         | Description                                                                 |\n| ------------------------------ | -------- | ------------------------------- | --------------------------------------------------------------------------- |\n| `MCP_HTTP_PORT`                | No       | `3000`                          | Port for the HTTP server                                                    |\n| `MCP_HTTP_TRANSPORT`           | No       | `stream`                        | Transport protocol (`stream` or `sse`). See [Transport Protocols](#transport-protocols) |\n| `MCP_HTTP_BIND_ADDR`           | No       | `127.0.0.1`                     | Bind address (IPv4/IPv6). Use adapter IP address to expose to the network.  |\n| `MCP_HTTP_PATH`                | No       | `/mcp` or `/sse`*               | Base path for MCP endpoints (*depends on transport)                         |\n| `MCP_HTTP_ENABLE_HEALTHCHECK`  | No       | `true`                          | Enable a healthcheck endpoint                                               |\n| `MCP_HTTP_HEALTHCHECK_PATH`    | No       | `/healthz`                      | Path for the healthcheck endpoint                                           |\n| `MCP_HTTP_ALLOW_CORS`          | No       | `true`                          | Enable CORS for the HTTP server                                             |\n| `MCP_HTTP_ALLOWED_ORIGINS`     | No       | `127.0.0.1, localhost`          | Comma-separated list of allowed origins. Use `*` to allow all (dev only)    |\n| `MCP_HTTP_NGROK_ENABLED`       | No       | `false`                         | Use ngrok to expose the HTTP server publicly                                |\n| `MCP_HTTP_NGROK_AUTH_TOKEN`    | No       | -                               | Ngrok auth token (required if `MCP_HTTP_NGROK_ENABLED=true`)                |\n\nCreate a `.env` file or export the variables before launching the container.\n\n## Transport Protocols\n\nThe MCP server supports two HTTP transport protocols:\n\n### Streamable HTTP (Default)\n\nThe **Streamable HTTP** transport implements the [MCP protocol version 2025-03-26](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#http-with-sse). This is the recommended transport for new integrations.\n\n```bash\ndocker run -d \\\n  --env-file .env \\\n  -e MCP_SERVER_USE_HTTP=true \\\n  -e MCP_HTTP_TRANSPORT=stream \\\n  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \\\n  -p 3000:3000 \\\n  jmtvms/tplink-omada-mcp:latest\n```\n\nFeatures:\n\n- Single endpoint for all operations (GET, POST, DELETE)\n- Server-Sent Events for streaming responses\n- Built-in session management with cryptographic session IDs\n- Support for stateless mode when needed\n\nThe Streamable HTTP endpoint defaults to `/mcp` and handles:\n\n- `GET /mcp` - Establish SSE stream and initialize session\n- `POST /mcp` - Send JSON-RPC messages\n- `DELETE /mcp` - Terminate session\n\n### HTTP with SSE (Legacy)\n\nThe **HTTP+SSE** transport implements the [MCP protocol version 2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse). This transport is provided for backward compatibility with older MCP clients.\n\n```bash\ndocker run -d \\\n  --env-file .env \\\n  -e MCP_SERVER_USE_HTTP=true \\\n  -e MCP_HTTP_TRANSPORT=sse \\\n  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \\\n  -p 3000:3000 \\\n  jmtvms/tplink-omada-mcp:latest\n```\n\nFeatures:\n\n- Separate endpoints for SSE stream and POST messages\n- Compatible with older MCP client implementations\n\nThe SSE transport uses two endpoints:\n\n- `GET /sse` - Establish SSE connection\n- `POST /messages` - Send JSON-RPC messages\n\n### Security Considerations\n\nBoth transports implement DNS rebinding protection:\n\n- **Origin Validation**: The server validates the `Origin` header on all incoming connections. Configure allowed origins with `MCP_HTTP_ALLOWED_ORIGINS` (default: `127.0.0.1, localhost`). Use `*` to allow all origins (development only, not recommended for production).\n- **Network Binding**: The server binds to `127.0.0.1` by default, restricting access to localhost only. Set `MCP_HTTP_BIND_ADDR=0.0.0.0` to expose the server to your network (not recommended for production without additional security measures).\n\nFor more information on the MCP protocol and transports, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).\n\n### Using ngrok\n\nTo share the local server with remote tooling, you can use ngrok to expose the HTTP server publicly. This works with **both stream and SSE transports**.\n\n**Built-in ngrok support**\n\n```bash\ndocker run -d \\\n  --env-file .env \\\n  -e MCP_SERVER_USE_HTTP=true \\\n  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \\\n  -e MCP_HTTP_NGROK_ENABLED=true \\\n  -e MCP_HTTP_NGROK_AUTH_TOKEN=your-ngrok-auth-token \\\n  -p 3000:3000 \\\n  jmtvms/tplink-omada-mcp:latest\n```\n\nThe server will automatically establish an ngrok tunnel and log the public URL.\n\nIf an intermediary strips the `Mcp-Session-Id` header, set `MCP_SERVER_STATEFUL=false` to disable server-managed sessions and allow stateless requests.\n\n## Tools\n\n| Tool                            | Description                                                                       |\n| ------------------------------- | --------------------------------------------------------------------------------- |\n| `listSites`                     | Lists all sites configured on the controller.                                     |\n| `listDevices`                   | Lists provisioned devices for a given site.                                       |\n| `listClients`                   | Lists active client devices for a site.                                           |\n| `getDevice`                     | Fetches details for a specific Omada device.                                      |\n| `getSwitchStackDetail`          | Retrieves detailed configuration and status for a switch stack.                   |\n| `getClient`                     | Fetches details for a specific client device.                                     |\n| `searchDevices`                 | Searches for devices globally across all sites the user has access to.            |\n| `listDevicesStats`              | Queries statistics for global adopted devices with pagination and filtering.      |\n| `getInternetInfo`               | Gets internet configuration information for a site.                               |\n| `getPortForwardingStatus`       | Gets port forwarding status and rules (User or UPnP types).                       |\n| `getLanNetworkList`             | Gets the list of LAN networks configured in a site.                               |\n| `getLanProfileList`             | Gets the list of LAN profiles configured in a site.                               |\n| `getWlanGroupList`              | Gets the list of WLAN groups configured in a site.                                |\n| `getSsidList`                   | Gets the list of SSIDs in a WLAN group.                                           |\n| `getSsidDetail`                 | Gets detailed information for a specific SSID.                                    |\n| `getFirewallSetting`            | Gets firewall configuration and rules for a site.                                 |\n\n## Supported Omada API Operations\n\n| Operation ID                        | Description                                               | Notes                                                                                                |\n| ----------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `getSiteList`                       | List controller sites.                                    | Backed by `listSites`; automatic pagination is handled client-side.                                  |\n| `getDeviceList`                     | List devices assigned to a site.                          | Used by `listDevices` and `getDevice` (single device lookup is resolved from this list).             |\n| `searchGlobalDevice`                | Search for devices across all accessible sites.           | Used by `searchDevices`; returns devices matching the search key globally.                           |\n| `getGridAdoptedDevicesStatByGlobal` | Query statistics for global adopted devices with filters. | Used by `listDevicesStats`; supports pagination and fuzzy search by MAC, name, model, or SN.         |\n| `getGridActiveClients`              | List active clients connected to a site.                  | Used by `listClients` and `getClient` (single client lookup is resolved from this list).             |\n| `getMostActiveClients`              | Get most active clients sorted by traffic.                | Used by `listMostActiveClients`; dashboard endpoint returning top clients by traffic usage.          |\n| `getClientActivity`                 | Get client activity statistics over time.                 | Used by `listClientsActivity`; returns time-series data of new, active, and disconnected clients.    |\n| `getGridPastConnections`            | Get client past connection list.                          | Used by `listClientsPastConnections`; supports pagination, filtering, sorting, and fuzzy search.     |\n| `getOswStackDetail`                 | Retrieve details for a switch stack.                      | Used by `getSwitchStackDetail`.                                                                      |\n| `getGlobalThreatList`               | Get global view threat management list.                   | Used by `getThreatList`; returns paginated security threats with filtering by time, severity, sites. |\n| `getInternet`                       | Get internet configuration info for a site.               | Used by `getInternetInfo`; returns WAN settings and connectivity details.                            |\n| `getPortForwardStatus`              | Get port forwarding status by type.                       | Used by `getPortForwardingStatus`; retrieves User or UPnP port forwarding rules.                     |\n| `getLanNetworkListV2`               | Get LAN network list (v2 API).                            | Used by `getLanNetworkList`; returns VLAN settings, IP ranges, DHCP configuration.                   |\n| `getLanProfileList`                 | Get LAN profile list.                                     | Used by `getLanProfileList`; returns network settings for switch ports.                              |\n| `getWlanGroupList`                  | Get WLAN group list.                                      | Used by `getWlanGroupList`; returns wireless network groups. Use wlanId for `getSsidList`.           |\n| `getSsidList`                       | Get SSID list for a WLAN group.                           | Used by `getSsidList`; requires wlanId from `getWlanGroupList`. Use ssidId for `getSsidDetail`.      |\n| `getSsidDetail`                     | Get detailed SSID configuration.                          | Used by `getSsidDetail`; requires wlanId and ssidId. Returns security, rate limits, scheduling.      |\n| `getFirewallSetting`                | Get firewall configuration for a site.                    | Used by `getFirewallSetting`; returns ACL rules, IP groups, security policies.                       |\n\n## Contributing\n\nWant to help improve this project? Contributions are welcome! Visit our GitHub repository to report issues, suggest features, or submit pull requests:\n\n**https://github.com/MiguelTVMS/tplink-omada-mcp**\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/MiguelTVMS/tplink-omada-mcp?tab=MIT-1-ov-file).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-k%2Fomada-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-k%2Fomada-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-k%2Fomada-mcp/lists"}