[Community Server] safe-omada-mcp: AI-native network management for TP-Link Omada controllers

[gaspareduard]

safe-omada-mcp

Repository: https://github.com/gaspareduard/Omada-mcp

npm: safe-omada-mcp

Description: Security-focused MCP server that exposes the TP-Link Omada Open API to Claude and other MCP-compatible AI agents. Instead of navigating the Omada web UI or writing custom scripts, you ask Claude — it handles diagnostics, configuration, backups, and network health checks through 364 verified tools.

What makes it different from a basic API wrapper:

• Composite tools — getNetworkHealthSummary, getGatewayHealth, diagnoseClient, getSecurityOverview each run 3–4 parallel API calls internally using Promise.allSettled, with graceful degradation if individual endpoints fail
• Dry-run on every mutation — every write tool supports dryRun: true so you see the planned action before it executes
• Capability profiles — safe-read (default, zero writes), ops-write (scoped mutations), admin (full access). Explicit control over how much the AI can touch.
• 364 verified tools across 40 API categories — every endpoint validated against the Omada Open API spec, not guessed
• 2,371 tests at 97%+ coverage — production-grade test discipline

Tools provided (highlights):

• getNetworkHealthSummary — dashboard overview + WAN status + client distribution + recent threats in one call
• getGatewayHealth — auto-discovers gateway, returns detail + WAN + LAN + ports in parallel
• diagnoseClient — resolves MAC/IP/hostname, returns status + detail + last 10 connection sessions
• getSecurityOverview — active threat list + firewall settings
• backupController / restoreController — controller backup/restore with dry-run support
• blockClient / unblockClient / reconnectClient — client management
• Full CRUD for ACL rules, DHCP reservations, firewall settings, VPN tunnels, and more

Install:

{
  "mcpServers": {
    "omada": {
      "command": "npx",
      "args": ["-y", "safe-omada-mcp"],
      "env": {
        "OMADA_BASE_URL": "https://your-controller",
        "OMADA_CLIENT_ID": "your-client-id",
        "OMADA_CLIENT_SECRET": "your-client-secret",
        "OMADA_OMADAC_ID": "your-omadac-id"
      }
    }
  }
}

Or via Docker:

docker run --rm -i \
  -e OMADA_BASE_URL=https://your-controller \
  -e OMADA_CLIENT_ID=your-client-id \
  -e OMADA_CLIENT_SECRET=your-client-secret \
  -e OMADA_OMADAC_ID=your-omadac-id \
  ghcr.io/gaspareduard/omada-mcp:latest

Stack: TypeScript · Node.js 24 · Zod · Biome · Vitest · MCP SDK
Supported controllers: Omada Software Controller 5.x/6.x, OC200, OC300