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

Capability and Logging

Capability Profiles

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.

Development and Validation

Common Commands

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

Device

Network

Firewall & ACL

Firewall Traffic & QoS

Firewall IDS / IPS

Security & Threat Management

Composite Troubleshooting Tools

Single-call tools that internally aggregate multiple Omada API calls in parallel. Use these instead of chaining individual tools when you need a quick overview or are starting a troubleshooting session.

Dashboard / Monitor

Insight

VPN

Profiles

Logs

Controller

Maintenance

Account Users

Account Cloud

Schedules

Supported Omada API Operations

Devcontainer support

The repository includes a ready-to-use devcontainer configuration with a dedicated Omada controller sidecar for local development and testing. See .devcontainer/README.md for details.

License

This project is licensed under the MIT License.