fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands - CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround - CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check - NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere - MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates - LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference Co-authored-by: Cursor <cursoragent@cursor.com>
157 lines
3.7 KiB
Markdown
157 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
Create or update `~/.env` with the following:
|
|
|
|
#### Private API Mode (Default)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|