proxmox/mcp-omada/README.md

Omada MCP Server

Model Context Protocol (MCP) server for managing TP-Link Omada devices through Claude Desktop and other MCP clients.

Features

• List and query Omada devices (routers, switches, access points)
• View VLAN configurations
• Get device statistics and status
• Reboot devices
• View firewall rules
• Query router WAN configurations
• Query switch port configurations

Installation

pnpm install
pnpm build

Configuration

Environment Variables

Create or update ~/.env with the following:

# Omada Controller Configuration
OMADA_CONTROLLER_URL=https://192.168.11.8:8043
OMADA_API_KEY=your-api-key
OMADA_API_SECRET=your-api-secret
OMADA_SITE_ID=your-site-id  # Optional, will use default site if not set
OMADA_VERIFY_SSL=false  # Set to true for production (requires valid SSL cert)

Recommended: Use the proxmox-controller API application (Client Credentials mode) for MCP automation:

• Client ID: 94327608913c41bb9c32ce8d1d6e87d3
• Client Secret: 600b924a541a4139a386cb7c63ac47b5

See the Physical Hardware Inventory for complete API credential details.

Getting API Credentials

1. Access your Omada Controller web interface
2. Navigate to Settings > Platform Integration > Open API
3. Click Add New App
4. Provide an app name and select Client Credentials mode
5. Save to get your Client ID (API Key) and Client Secret

Claude Desktop Integration

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "omada": {
      "command": "node",
      "args": ["/path/to/proxmox/mcp-omada/dist/index.js"]
    }
  }
}

Config File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Available Tools

omada_list_devices

List all Omada devices (routers, switches, access points).

Parameters:

• deviceType (optional): Filter by type - 'router', 'switch', 'ap', or 'all'
• siteId (optional): Site ID (uses default if not provided)

omada_get_device

Get detailed information about a specific device.

Parameters:

• deviceId (required): Device ID
• siteId (optional): Site ID

omada_list_vlans

List all VLANs configured in the Omada Controller.

Parameters:

• siteId (optional): Site ID

omada_get_vlan

Get VLAN configuration details.

Parameters:

• vlanId (required): VLAN ID
• siteId (optional): Site ID

omada_reboot_device

Reboot a device.

Parameters:

• deviceId (required): Device ID to reboot
• siteId (optional): Site ID

omada_get_device_statistics

Get device statistics (CPU, memory, traffic).

Parameters:

• deviceId (required): Device ID
• siteId (optional): Site ID

omada_list_firewall_rules

List firewall rules.

Parameters:

• siteId (optional): Site ID

omada_get_switch_ports

Get switch port configuration (for SG218R and other switches).

Parameters:

• deviceId (required): Switch device ID
• siteId (optional): Site ID

omada_get_router_wan

Get router WAN port configuration (for ER605 and other routers).

Parameters:

• deviceId (required): Router device ID
• siteId (optional): Site ID

omada_list_sites

List all sites in the Omada Controller.

Parameters: None

Usage Examples

Once configured, you can ask Claude Desktop:

• "List all routers in my Omada network"
• "Show me the VLAN configurations"
• "Get statistics for device XYZ"
• "What are the WAN settings for router ABC?"
• "Show me the ports on switch DEF"

Troubleshooting

Connection Errors

• Verify OMADA_CONTROLLER_URL is correct (IP address and port 8043)
• Check that the Omada Controller is running and accessible
• If using self-signed certificates, ensure OMADA_VERIFY_SSL=false

Authentication Errors

• Verify OMADA_API_KEY and OMADA_API_SECRET are correct
• Check that the API app is enabled in Omada Controller
• Ensure the API app has the necessary permissions

Device Not Found

• Verify the deviceId is correct
• Check that siteId matches the device's site (if provided)
• Ensure the device is adopted and online