Safe Omada MCP

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:

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

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

   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:

   {
     "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

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 th

... View full README on GitHub