cb47cce074
- Organized 252 files across project - Root directory: 187 → 2 files (98.9% reduction) - Moved configuration guides to docs/04-configuration/ - Moved troubleshooting guides to docs/09-troubleshooting/ - Moved quick start guides to docs/01-getting-started/ - Moved reports to reports/ directory - Archived temporary files - Generated comprehensive reports and documentation - Created maintenance scripts and guides All files organized according to established standards.
180 lines
4.2 KiB
Markdown
180 lines
4.2 KiB
Markdown
# 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
|
|
|