Omada Mcp

Omada MCP Server

Full CRUD MCP server for TP-Link Omada SDN controllers. Exposes 60+ tools for reading, writing, and managing sites, devices, clients, networks, switch ports, firewalls, and more — all via the Model Context Protocol.

Quick Start

Using with Claude Code / Claude Desktop (stdio)

Add to your MCP client configuration:

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": ["/path/to/omada-mcp/dist/index.js"],
      "env": {
        "OMADA_BASE_URL": "https://your-omada-controller.local",
        "OMADA_CLIENT_ID": "your-client-id",
        "OMADA_CLIENT_SECRET": "your-client-secret",
        "OMADA_OMADAC_ID": "your-omadac-id",
        "OMADA_SITE_ID": "your-site-id",
        "OMADA_STRICT_SSL": "false"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "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=false",
        "jmtvms/tplink-omada-mcp:latest"
      ]
    }
  }
}

Docker HTTP Server

docker run -d \
  --env-file .env \
  -e MCP_SERVER_USE_HTTP=true \
  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
  -p 3000:3000 \
  jmtvms/tplink-omada-mcp:latest

Available at http://localhost:3000/mcp (stream) or http://localhost:3000/sse (SSE).

Environment Variables

Omada Controller

| Variable | Required | Default | Description | |---|---|---|---| | OMADA_BASE_URL | Yes | - | Omada controller URL | | OMADA_CLIENT_ID | Yes | - | OAuth client ID | | OMADA_CLIENT_SECRET | Yes | - | OAuth client secret | | OMADA_OMADAC_ID | Yes | - | Controller ID (omadacId) | | OMADA_SITE_ID | No | - | Default site ID | | OMADA_STRICT_SSL | No | true | SSL verification (false for self-signed) | | OMADA_TIMEOUT | No | 30000 | Request timeout (ms) |

MCP Server

| Variable | Required | Default | Description | |---|---|---|---| | MCP_SERVER_LOG_LEVEL | No | info | debug, info, warn, error, silent | | MCP_SERVER_LOG_FORMAT | No | plain | plain, json, gcp-json | | MCP_SERVER_USE_HTTP | No | false | Enable HTTP transport | | MCP_SERVER_STATEFUL | No | false | Stateful sessions | | MCP_HTTP_PORT | No | 3000 | HTTP port | | MCP_HTTP_TRANSPORT | No | stream | stream or sse | | MCP_HTTP_BIND_ADDR | No | 127.0.0.1 | Bind address |

Tools

Read Tools

| Tool | Description | |---|---| | listSites | List all sites on the controller | | listDevices | List devices for a site | | listClients | List active clients for a site | | getDevice | Get details for a specific device | | getClient | Get details for a specific client | | getSwitchStackDetail | Get switch stack configuration and status | | searchDevices | Search devices globally across all sites | | listDevicesStats | Device statistics with pagination and filtering | | listMostActiveClients | Top clients sorted by traffic | | listClientsActivity | Client activity time-series data | | listClientsPastConnections | Historical client connections | | getThreatList | Security threat list with filtering | | getInternetInfo | Internet / WAN configuration | | getPortForwardingStatus | Port forwarding rules (User/UPnP) | | getLanNetworkList | LAN networks and VLAN settings | | getLanProfileList | LAN profiles for switch ports | | getWlanGroupList | WLAN groups | | getSsidList | SSIDs in a WLAN group | | getSsidDetail | Detailed SSID configuration | | getFirewallSetting | Firewall rules and policies | | getSwitchPorts | All ports for a switch (status, PoE, speed, STP) | | getFirmwareDetails | Firmware info for a device | | listEvents | Paginated site events | | listLogs | Paginated site logs | | listFirewallAcls | Firewall ACL rules | | listRoutes | Static routes | | getSwitch | Full switch info including portList array | | getCableTestResults | Cable test results for a switch | | getSwitchNetworks | Switch VLAN trunking configuration |

Write Tools

| Tool | Description | |---|---| | createLanNetwork | Create a LAN network | | updateLanNetwork | Update a LAN network | | deleteLanNetwork | Delete a LAN network | | createLanProfile | Create a LAN profile | | updateLanProfile | Update a LAN profile | | updateFirewallSetting | Update firewall settings | | createFirewallAcl | Create a firewall ACL rule | | deleteFirewallAcl | Delete a firewall ACL rule | | updateSwitchPort | Update switch port config (profile, PoE, speed, STP) | | updateClient | Update client settings | | setSwitchNetworks | Set switch VLAN trunking configuration |

Switch Port Tools

| Tool | Description | |---|---| | setSwitchPortProfile | Assign a LAN profile to a single port | | setSwitchPortPoe | Enable/disable PoE on a single port | | setSwitchPortName | Set name on a single port | | setSwitchPortStatus | Enable/disable a single port | | setSwitchPortProfileOverride | Enable/disable profile override on a single port | | batchSetSwitchPortProfile | Batch profile override on multiple ports | | batchSetSwitchPortPoe | Batch PoE on multiple ports | | batchSetSwitchPortStatus | Batch enable/disable multiple ports | | batchSetSwitchPortName | Batch set names on multiple ports | | startCableTest | Start cable test on a switch |

Action Tools

| Tool | Description | |---|---| | rebootDevice | Reboot a device | | adoptDevice | Adopt a device | | blockClient | Block a client | | unblockClient | Unblock a client | | reconnectClient | Reconnect a client | | setDeviceLed | Set device LED setting | | startFirmwareUpgrade | Start firmware upgrade | | setGatewayWanConnect | Connect/disconnect gateway WAN port |

Generic

| Tool | Description | |---|---| | genericApiCall | Invoke any Omada OpenAPI endpoint directly |

Development

npm install
npm run dev          # Live reload via tsx
npm run build        # Compile TypeScript
npm run check        # Lint + type check
npm start            # Run compiled server (stdio)

Docker

npm run docker:build   # Build image
npm run docker:run     # Run with .env file

Credits

Forked from jmtvms/tplink-omada-mcp. Extended with full CRUD operations, switch port management, batch operations, and cable testing by realtydev/omada-mcp.

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: realtydev
• Source: realtydev/omada-mcp
• License: MIT

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