unifi-pro-mcp/docs/api-reference.md

MCP Server for UniFi Network and Protect systems with multi-device support

# API Reference

Complete reference for all UniFi PRO MCP tools, resources, and methods.

## 📋 Table of Contents

- [Overview](#overview)
- [Authentication](#authentication)
- [Device Management](#device-management)
- [Client Management](#client-management)
- [Network Configuration](#network-configuration)
- [Monitoring & Analytics](#monitoring--analytics)
- [Security Management](#security-management)
- [Site Administration](#site-administration)
- [Backup & Restore](#backup--restore)
- [Error Handling](#error-handling)
- [TypeScript Types](#typescript-types)

## 🔍 Overview

The UniFi PRO MCP provides a comprehensive set of tools for managing UniFi networks through the Model Context Protocol. All tools return structured data and support various parameters for filtering and customization.

### Tool Categories

| Category | Tools | Description |
|----------|-------|-------------|
| **Devices** | 8 tools | Hardware management and monitoring |
| **Clients** | 6 tools | Connected device management |
| **Network** | 7 tools | Configuration and settings |
| **Analytics** | 5 tools | Performance and usage statistics |
| **Security** | 4 tools | Firewall and access control |
| **Administration** | 6 tools | Site and system management |

### Response Format

All tools return responses in this standard format:

```typescript
interface MCPResponse {
  success: boolean;
  data?: any;
  error?: string;
  timestamp: string;
  metadata?: {
    controller: string;
    site: string;
    version: string;
  };
}
```

## 🔐 Authentication

All API calls are automatically authenticated using the configured credentials. No explicit authentication tools are exposed for security reasons.

## 📱 Device Management

### `unifi_get_devices`

List all UniFi devices in the network.

**Parameters:**
```typescript
interface GetDevicesParams {
  site?: string;           // Site ID (default: configured site)
  type?: DeviceType;       // Filter by device type
  state?: DeviceState;     // Filter by device state
  includeStats?: boolean;  // Include performance statistics
}

type DeviceType = 'uap' | 'usw' | 'ugw' | 'usg' | 'uck' | 'udm' | 'udr' | 'uxg';
type DeviceState = 'online' | 'offline' | 'pending' | 'upgrading';
```

**Example:**
```javascript
// Get all access points
{
  "tool": "unifi_get_devices",
  "parameters": {
    "type": "uap",
    "includeStats": true
  }
}
```

**Response:**
```typescript
interface Device {
  id: string;
  mac: string;
  model: string;
  name: string;
  type: DeviceType;
  state: DeviceState;
  version: string;
  uptime: number;
  ip: string;
  adopted: boolean;
  location?: {
    lat?: number;
    lng?: number;
    altitude?: number;
  };
  stats?: DeviceStats;
}

interface DeviceStats {
  cpu: number;          // CPU usage percentage
  memory: number;       // Memory usage percentage
  temperature: number;  // Temperature in Celsius  
  uptime: number;      // Uptime in seconds
  loadavg: number[];   // Load average
}
```

### `unifi_get_device_status`

Get detailed status information for a specific device.

**Parameters:**
```typescript
interface GetDeviceStatusParams {
  deviceId: string;     // Device ID or MAC address
  site?: string;        // Site ID
  includeRadioStats?: boolean;  // Include WiFi radio statistics
  includePortStats?: boolean;   // Include switch port statistics
}
```

**Example:**
```javascript
{
  "tool": "unifi_get_device_status", 
  "parameters": {
    "deviceId": "5f8a123456789abc",
    "includeRadioStats": true
  }
}
```

**Response:**
```typescript
interface DeviceStatus extends Device {
  radioStats?: RadioStats[];
  portStats?: PortStats[];
  systemStats: SystemStats;
  alerts: Alert[];
}

interface RadioStats {
  radio: 'ng' | 'na' | 'ad';  // 2.4GHz, 5GHz, 6GHz
  channel: number;
  power: number;             // TX power in dBm
  utilization: number;       // Channel utilization percentage
  clients: number;           // Connected clients count
}
```

### `unifi_restart_device`

Restart a UniFi device remotely.

**Parameters:**
```typescript
interface RestartDeviceParams {
  deviceId: string;     // Device ID or MAC address
  site?: string;        // Site ID
  force?: boolean;      // Force restart even if clients connected
}
```

**Example:**
```javascript
{
  "tool": "unifi_restart_device",
  "parameters": {
    "deviceId": "5f8a123456789abc",
    "force": false
  }
}
```

### `unifi_adopt_device`

Adopt a new UniFi device into the network.

**Parameters:**
```typescript
interface AdoptDeviceParams {
  deviceMac: string;    // MAC address of device to adopt
  site?: string;        // Site ID
  name?: string;        // Custom device name
}
```

### `unifi_upgrade_device`

Upgrade device firmware.

**Parameters:**
```typescript
interface UpgradeDeviceParams {
  deviceId: string;     // Device ID or MAC address
  version?: string;     // Target firmware version (latest if not specified)
  site?: string;        // Site ID
}
```

### `unifi_locate_device`

Activate device LED for physical identification.

**Parameters:**
```typescript
interface LocateDeviceParams {
  deviceId: string;     // Device ID or MAC address
  enable: boolean;      // Enable/disable locate LED
  site?: string;        // Site ID
}
```

### `unifi_get_device_config`

Get device configuration details.

**Parameters:**
```typescript
interface GetDeviceConfigParams {
  deviceId: string;     // Device ID or MAC address  
  site?: string;        // Site ID
}
```

### `unifi_update_device_config`

Update device configuration.

**Parameters:**
```typescript
interface UpdateDeviceConfigParams {
  deviceId: string;     // Device ID or MAC address
  config: Partial<DeviceConfig>;  // Configuration updates
  site?: string;        // Site ID
}

interface DeviceConfig {
  name?: string;
  led_override?: 'default' | 'on' | 'off';
  power_source_ctrl_enabled?: boolean;
  outlet_overrides?: OutletOverride[];
}
```

## 👥 Client Management

### `unifi_get_clients`

List all connected clients.

**Parameters:**
```typescript
interface GetClientsParams {
  site?: string;           // Site ID
  state?: ClientState;     // Filter by connection state  
  type?: ClientType;       // Filter by client type
  includeUsage?: boolean;  // Include bandwidth usage stats
  limit?: number;          // Maximum results (default: 100)
}

type ClientState = 'online' | 'offline' | 'blocked';
type ClientType = 'wireless' | 'wired' | 'guest';
```

**Response:**
```typescript
interface Client {
  id: string;
  mac: string;
  ip: string;
  hostname?: string;
  name?: string;
  oui: string;           // Manufacturer OUI
  state: ClientState;
  type: ClientType;
  network: string;       // Network name
  ap_mac?: string;       // Connected AP MAC (wireless only)
  channel?: number;      // WiFi channel (wireless only)
  signal?: number;       // Signal strength in dBm (wireless only)
  usage?: ClientUsage;
  first_seen: number;    // Unix timestamp
  last_seen: number;     // Unix timestamp
}

interface ClientUsage {
  rx_bytes: number;      // Bytes received
  tx_bytes: number;      // Bytes transmitted
  rx_rate: number;       // Current RX rate (bps)
  tx_rate: number;       // Current TX rate (bps)
}
```

### `unifi_get_client_details`

Get detailed information about a specific client.

**Parameters:**
```typescript
interface GetClientDetailsParams {
  clientId: string;      // Client ID or MAC address
  site?: string;         // Site ID
  includeHistory?: boolean;  // Include connection history
}
```

### `unifi_block_client`

Block or unblock a client.

**Parameters:**
```typescript
interface BlockClientParams {
  clientId: string;      // Client ID or MAC address
  blocked: boolean;      // Block (true) or unblock (false)
  site?: string;         // Site ID
}
```

### `unifi_get_client_usage`

Get bandwidth usage statistics for clients.

**Parameters:**
```typescript
interface GetClientUsageParams {
  site?: string;         // Site ID
  period?: TimePeriod;   // Time period for statistics
  limit?: number;        // Top N clients by usage
  sortBy?: 'rx_bytes' | 'tx_bytes' | 'total_bytes';
}

type TimePeriod = '5m' | '1h' | '1d' | '7d' | '30d';
```

### `unifi_authorize_guest`

Authorize guest network access.

**Parameters:**
```typescript
interface AuthorizeGuestParams {
  clientMac: string;     // Guest client MAC address
  duration: number;      // Access duration in minutes
  bandwidth?: {          // Optional bandwidth limits
    down: number;        // Download limit (Kbps)
    up: number;          // Upload limit (Kbps)
  };
  site?: string;         // Site ID
}
```

### `unifi_kick_client`

Disconnect a client from the network.

**Parameters:**
```typescript
interface KickClientParams {
  clientId: string;      // Client ID or MAC address
  site?: string;         // Site ID
}
```

## 🌐 Network Configuration

### `unifi_get_networks`

List all configured networks.

**Parameters:**
```typescript
interface GetNetworksParams {
  site?: string;         // Site ID
  includeStats?: boolean;  // Include network statistics
}
```

**Response:**
```typescript
interface Network {
  id: string;
  name: string;
  purpose: 'corporate' | 'guest' | 'wan' | 'vlan';
  vlan: number;
  subnet: string;        // CIDR notation
  dhcp_enabled: boolean;
  dhcp_range_start?: string;
  dhcp_range_stop?: string;
  domain_name?: string;
  enabled: boolean;
  stats?: NetworkStats;
}
```

### `unifi_get_wifi_settings`

Get WiFi network configuration.

**Parameters:**
```typescript
interface GetWiFiSettingsParams {
  site?: string;         // Site ID
  networkId?: string;    // Specific network ID
}
```

### `unifi_update_wifi_settings`

Update WiFi network configuration.

**Parameters:**
```typescript
interface UpdateWiFiSettingsParams {
  networkId: string;     // Network ID to update
  settings: Partial<WiFiSettings>;
  site?: string;         // Site ID
}

interface WiFiSettings {
  name?: string;         // SSID name
  password?: string;     // Network password
  security?: 'open' | 'wep' | 'wpa' | 'wpa2' | 'wpa3';
  wpa_mode?: 'wpa' | 'wpa2' | 'wpa_mixed';
  wpa_enc?: 'auto' | 'ccmp' | 'tkip';
  enabled?: boolean;     // Enable/disable network
  hide_ssid?: boolean;   // Hide SSID broadcast
  mac_filter_enabled?: boolean;
  mac_filter_policy?: 'allow' | 'deny';
}
```

### `unifi_get_port_profiles`

Get switch port profiles.

**Parameters:**
```typescript
interface GetPortProfilesParams {
  site?: string;         // Site ID
}
```

### `unifi_create_network`

Create a new network.

**Parameters:**
```typescript
interface CreateNetworkParams {
  name: string;          // Network name
  purpose: 'corporate' | 'guest' | 'vlan';
  vlan?: number;         // VLAN ID
  subnet?: string;       // Subnet in CIDR notation
  dhcp_enabled?: boolean;
  site?: string;         // Site ID
}
```

### `unifi_update_port_config`

Update switch port configuration.

**Parameters:**
```typescript
interface UpdatePortConfigParams {
  deviceId: string;      // Switch device ID
  portId: number;        // Port number
  config: PortConfig;
  site?: string;         // Site ID
}

interface PortConfig {
  profile_id?: string;   // Port profile ID
  name?: string;         // Port name/description
  poe_mode?: 'off' | 'auto' | 'passive24' | 'passthrough';
  port_security_enabled?: boolean;
}
```

### `unifi_get_dhcp_leases`

Get DHCP lease information.

**Parameters:**
```typescript
interface GetDHCPLeasesParams {
  site?: string;         // Site ID
  networkId?: string;    // Specific network
}
```

## 📊 Monitoring & Analytics

### `unifi_get_site_stats`

Get overall site statistics.

**Parameters:**
```typescript
interface GetSiteStatsParams {
  site?: string;         // Site ID
  period?: TimePeriod;   // Time period for statistics
}
```

**Response:**
```typescript
interface SiteStats {
  devices: {
    total: number;
    online: number;
    offline: number;
    by_type: Record<DeviceType, number>;
  };
  clients: {
    total: number;
    wireless: number;
    wired: number;
    guest: number;
  };
  traffic: {
    rx_bytes: number;
    tx_bytes: number;
    rx_rate: number;      // Current RX rate
    tx_rate: number;      // Current TX rate
  };
  health: {
    wan: number;          // WAN health score (0-100)
    lan: number;          // LAN health score (0-100)
    wlan: number;         // WLAN health score (0-100)
  };
}
```

### `unifi_get_health_metrics`

Get system health metrics.

**Parameters:**
```typescript
interface GetHealthMetricsParams {
  site?: string;         // Site ID
  includeHistory?: boolean;  // Include historical data
}
```

### `unifi_generate_report`

Generate custom network reports.

**Parameters:**
```typescript
interface GenerateReportParams {
  type: ReportType;
  period: TimePeriod;
  site?: string;
  options?: ReportOptions;
}

type ReportType = 'usage' | 'performance' | 'security' | 'inventory' | 'clients';

interface ReportOptions {
  format?: 'json' | 'csv' | 'pdf';
  includeCharts?: boolean;
  email?: string;        // Email report to address
}
```

### `unifi_get_alerts`

Get active network alerts.

**Parameters:**
```typescript
interface GetAlertsParams {
  site?: string;         // Site ID
  severity?: AlertSeverity;  // Filter by severity
  category?: AlertCategory;  // Filter by category
  limit?: number;        // Maximum alerts to return
}

type AlertSeverity = 'info' | 'warning' | 'error' | 'critical';
type AlertCategory = 'device' | 'network' | 'security' | 'performance';
```

**Response:**
```typescript
interface Alert {
  id: string;
  timestamp: number;     // Unix timestamp
  severity: AlertSeverity;
  category: AlertCategory;
  message: string;
  details?: string;
  device_id?: string;
  resolved: boolean;
  acknowledged: boolean;
}
```

### `unifi_get_bandwidth_usage`

Get bandwidth usage statistics.

**Parameters:**
```typescript
interface GetBandwidthUsageParams {
  site?: string;         // Site ID
  period: TimePeriod;
  granularity?: '5m' | '1h' | '1d';  // Data point granularity
  device_id?: string;    // Specific device
  client_id?: string;    // Specific client
}
```

## 🔒 Security Management

### `unifi_get_firewall_rules`

Get firewall rules configuration.

**Parameters:**
```typescript
interface GetFirewallRulesParams {
  site?: string;         // Site ID
  ruleset?: 'wan' | 'lan' | 'guest' | 'vpn';
  enabled?: boolean;     // Filter enabled/disabled rules
}
```

**Response:**
```typescript
interface FirewallRule {
  id: string;
  name: string;
  action: 'accept' | 'drop' | 'reject';
  protocol: 'all' | 'tcp' | 'udp' | 'icmp';
  src_address?: string;  // Source IP/CIDR
  dst_address?: string;  // Destination IP/CIDR
  src_port?: string;     // Source port(s)
  dst_port?: string;     // Destination port(s)
  enabled: boolean;
  logging: boolean;
  rule_index: number;    // Rule order
}
```

### `unifi_manage_firewall_rules`

Create, update, or delete firewall rules.

**Parameters:**
```typescript
interface ManageFirewallRulesParams {
  action: 'create' | 'update' | 'delete';
  rule: FirewallRule;
  site?: string;
}
```

### `unifi_get_threat_management`

Get threat management status and logs.

**Parameters:**
```typescript
interface GetThreatManagementParams {
  site?: string;         // Site ID
  period?: TimePeriod;   // Time period for threat logs
  category?: ThreatCategory;
}

type ThreatCategory = 'malware' | 'phishing' | 'botnet' | 'intrusion';
```

### `unifi_update_security_settings`

Update security settings.

**Parameters:**
```typescript
interface UpdateSecuritySettingsParams {
  settings: SecuritySettings;
  site?: string;
}

interface SecuritySettings {
  ips_enabled?: boolean;     // Intrusion Prevention System
  dpi_enabled?: boolean;     // Deep Packet Inspection
  threat_management?: {
    honeypot_enabled: boolean;
    malware_enabled: boolean;
    ad_blocking_enabled: boolean;
  };
  content_filtering?: {
    enabled: boolean;
    categories: string[];
  };
}
```

## 🏢 Site Administration

### `unifi_get_sites`

List all sites (for multi-site deployments).

**Parameters:**
```typescript
interface GetSitesParams {
  includeStats?: boolean;  // Include site statistics
}
```

### `unifi_get_site_settings`

Get site configuration settings.

**Parameters:**
```typescript
interface GetSiteSettingsParams {
  site?: string;         // Site ID
  category?: SettingsCategory;
}

type SettingsCategory = 'connectivity' | 'guest_access' | 'wifi' | 'networks' | 'services';
```

### `unifi_update_site_settings`

Update site configuration settings.

**Parameters:**
```typescript
interface UpdateSiteSettingsParams {
  settings: Partial<SiteSettings>;
  site?: string;
}

interface SiteSettings {
  name?: string;
  description?: string;
  timezone?: string;
  country_code?: string;
  locale?: string;
  auto_upgrade?: boolean;
  guest_access?: GuestAccessSettings;
}
```

### `unifi_get_admins`

List site administrators.

**Parameters:**
```typescript
interface GetAdminsParams {
  site?: string;         // Site ID
}
```

### `unifi_get_events`

Get system events and logs.

**Parameters:**
```typescript
interface GetEventsParams {
  site?: string;         // Site ID
  limit?: number;        // Maximum events
  category?: EventCategory;
  start?: number;        // Start timestamp
  end?: number;          // End timestamp
}

type EventCategory = 'admin' | 'device' | 'client' | 'security' | 'system';
```

### `unifi_get_system_info`

Get controller system information.

**Parameters:**
```typescript
interface GetSystemInfoParams {
  detailed?: boolean;    // Include detailed system metrics
}
```

## 💾 Backup & Restore

### `unifi_backup_configuration`

Create a configuration backup.

**Parameters:**
```typescript
interface BackupConfigurationParams {
  site?: string;         // Site ID
  includeHistory?: boolean;  // Include historical data
  format?: 'ubf' | 'json';   // Backup format
}
```

### `unifi_list_backups`

List available configuration backups.

**Parameters:**
```typescript
interface ListBackupsParams {
  site?: string;         // Site ID
  limit?: number;        // Maximum backups to list
}
```

### `unifi_restore_configuration`

Restore from a configuration backup.

**Parameters:**
```typescript
interface RestoreConfigurationParams {
  backupId: string;      // Backup ID to restore
  site?: string;         // Site ID
  confirmRestart?: boolean;  // Confirm controller restart
}
```

### `unifi_download_backup`

Download a backup file.

**Parameters:**
```typescript
interface DownloadBackupParams {
  backupId: string;      // Backup ID
  site?: string;         // Site ID
}
```

## ❌ Error Handling

### Error Response Format

All tools return errors in a consistent format:

```typescript
interface MCPError {
  success: false;
  error: string;
  code: ErrorCode;
  details?: any;
  timestamp: string;
}

enum ErrorCode {
  AUTHENTICATION_FAILED = 'AUTHENTICATION_FAILED',
  NETWORK_ERROR = 'NETWORK_ERROR',
  INVALID_PARAMETERS = 'INVALID_PARAMETERS',
  DEVICE_NOT_FOUND = 'DEVICE_NOT_FOUND',
  CLIENT_NOT_FOUND = 'CLIENT_NOT_FOUND',
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  CONTROLLER_UNREACHABLE = 'CONTROLLER_UNREACHABLE',
  SITE_NOT_FOUND = 'SITE_NOT_FOUND',
  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
  RATE_LIMITED = 'RATE_LIMITED'
}
```

### Common Errors

| Error Code | Description | Solutions |
|------------|-------------|-----------|
| `AUTHENTICATION_FAILED` | Invalid credentials | Check username/password, verify user permissions |
| `NETWORK_ERROR` | Cannot reach controller | Check network connectivity, firewall rules |
| `INVALID_PARAMETERS` | Invalid tool parameters | Review parameter types and required fields |
| `DEVICE_NOT_FOUND` | Device ID not found | Verify device exists and is adopted |
| `PERMISSION_DENIED` | Insufficient privileges | Use admin account or adjust user permissions |
| `RATE_LIMITED` | Too many requests | Reduce request frequency, implement backoff |

## 📝 TypeScript Types

### Complete Type Definitions

```typescript
// Export all types for TypeScript users
export * from './types/devices';
export * from './types/clients';
export * from './types/networks';
export * from './types/analytics';
export * from './types/security';
export * from './types/administration';

// Main MCP Client interface
export interface UniFiMCPClient {
  // Device Management
  getDevices(params?: GetDevicesParams): Promise<MCPResponse<Device[]>>;
  getDeviceStatus(params: GetDeviceStatusParams): Promise<MCPResponse<DeviceStatus>>;
  restartDevice(params: RestartDeviceParams): Promise<MCPResponse<boolean>>;
  adoptDevice(params: AdoptDeviceParams): Promise<MCPResponse<boolean>>;
  
  // Client Management  
  getClients(params?: GetClientsParams): Promise<MCPResponse<Client[]>>;
  getClientDetails(params: GetClientDetailsParams): Promise<MCPResponse<ClientDetails>>;
  blockClient(params: BlockClientParams): Promise<MCPResponse<boolean>>;
  
  // Network Configuration
  getNetworks(params?: GetNetworksParams): Promise<MCPResponse<Network[]>>;
  getWiFiSettings(params?: GetWiFiSettingsParams): Promise<MCPResponse<WiFiSettings[]>>;
  updateWiFiSettings(params: UpdateWiFiSettingsParams): Promise<MCPResponse<boolean>>;
  
  // Monitoring & Analytics
  getSiteStats(params?: GetSiteStatsParams): Promise<MCPResponse<SiteStats>>;
  getHealthMetrics(params?: GetHealthMetricsParams): Promise<MCPResponse<HealthMetrics>>;
  generateReport(params: GenerateReportParams): Promise<MCPResponse<Report>>;
  
  // Security Management
  getFirewallRules(params?: GetFirewallRulesParams): Promise<MCPResponse<FirewallRule[]>>;
  manageFirewallRules(params: ManageFirewallRulesParams): Promise<MCPResponse<boolean>>;
  
  // Site Administration
  getSites(params?: GetSitesParams): Promise<MCPResponse<Site[]>>;
  getSiteSettings(params?: GetSiteSettingsParams): Promise<MCPResponse<SiteSettings>>;
  updateSiteSettings(params: UpdateSiteSettingsParams): Promise<MCPResponse<boolean>>;
}
```

---

**Next Steps:**
- [Usage Examples](examples.md) - See real-world scenarios
- [Security Guide](security.md) - Security best practices  
- [Installation Guide](installation.md) - Setup and configuration