proxmox/mcp-unifi

UniFi MCP Server

Model Context Protocol (MCP) server for managing Ubiquiti UniFi/UDM Pro devices through Claude Desktop and other MCP clients.

Features

• List and query UniFi devices (APs, switches, gateways)
• View client/station information
• Get network and VLAN configurations
• View WLAN/WiFi configurations
• Monitor events and alarms
• Get system information and health status

Installation

pnpm install
pnpm build

Configuration

Environment Variables

Create or update ~/.env with the following:

Private API Mode (Default)

# UniFi Controller Configuration
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
UNIFI_SITE_ID=default  # Optional, will use default site if not set
UNIFI_API_MODE=private  # Optional, defaults to private
UNIFI_VERIFY_SSL=false  # Set to true for production (requires valid SSL cert)

Official API Mode

# UniFi Controller Configuration
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_API_KEY=your-api-key
UNIFI_SITE_ID=default  # Optional, will use default site if not set
UNIFI_API_MODE=official
UNIFI_VERIFY_SSL=false  # Set to true for production (requires valid SSL cert)

Getting API Credentials

Official API (API Key)

1. Access your UniFi Network app
2. Navigate to Settings → Control Plane → Integrations
3. Generate an API key
4. Use the API key in UNIFI_API_KEY environment variable

Private API (Username/Password)

• Use your UniFi Controller admin username and password
• Private API uses cookie-based session authentication

Claude Desktop Integration

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": ["/path/to/proxmox/mcp-unifi/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

Site Management

• unifi_list_sites - List all sites
• unifi_get_site_stats - Get site statistics

Device Management

• unifi_list_devices - List all devices
• unifi_get_device - Get device by MAC address
• unifi_get_device_stats - Get device statistics

Client Management

• unifi_list_clients - List all active clients
• unifi_get_client - Get client by ID or MAC address

Network Management

• unifi_list_networks - List all networks/VLANs
• unifi_get_network - Get network by ID

WLAN Management

• unifi_list_wlans - List all WLAN configurations
• unifi_get_wlan - Get WLAN by ID

Events & Monitoring

• unifi_list_events - List events
• unifi_list_alarms - List alarms

System Operations

• unifi_get_system_info - Get system information
• unifi_get_health - Get site health status

Usage Examples

Once configured, you can ask Claude Desktop:

• "List all devices in my UniFi network"
• "Show me the active clients"
• "What are the network configurations?"
• "Get system information"
• "Show me recent events"
• "What's the health status of the site?"

Troubleshooting

Connection Errors

• Verify UNIFI_UDM_URL is correct (IP address or hostname)
• Check that the UniFi Controller is running and accessible
• If using self-signed certificates, ensure UNIFI_VERIFY_SSL=false

Authentication Errors

• For Private API: Verify UNIFI_USERNAME and UNIFI_PASSWORD are correct
• For Official API: Verify UNIFI_API_KEY is correct and valid
• Check that the API mode matches your credentials

Device/Client Not Found

• Verify IDs/MAC addresses are correct
• Check that siteId matches the device's site (if provided)
• Ensure the device/client is adopted and online

License

MIT