# 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

```bash
pnpm install
pnpm build
```

## Configuration

### Environment Variables

Create or update `~/.env` with the following:

```bash
# 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](../config/physical-hardware-inventory.md) 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:

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