# UniFi MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
A Model Context Protocol (MCP) server for UniFi Network management, providing 24 powerful tools for comprehensive network control, monitoring, and automation.
## Features
This MCP server provides complete UniFi Network management capabilities through Claude and other MCP clients:
### Site Management (3 tools)
- **Site Health Monitoring** - Get overall site health status and subsystem scores
- **Site Statistics** - Comprehensive network usage and performance metrics
- **System Information** - Controller version, hostname, and configuration details
### Device Management (6 tools)
- **List Devices** - View all UniFi devices (APs, switches, gateways) with status
- **Device Details** - Get detailed information for specific devices by MAC address
- **Device Statistics** - Real-time performance metrics and usage stats
- **Restart Device** - Remotely restart any UniFi device
- **Adopt Device** - Adopt pending devices into your network
- **Locate Device** - Enable/disable LED blink for physical device identification
### Client Management (5 tools)
- **List Clients** - View all connected clients (wireless/wired/all)
- **Client Details** - Get detailed information about specific clients
- **Block Client** - Block clients from network access by MAC address
- **Unblock Client** - Restore network access for blocked clients
- **Reconnect Client** - Force clients to reconnect (kick and allow rejoin)
### Wireless Network Management (5 tools)
- **List Networks** - View all configured networks and VLANs
- **List WLANs** - View all wireless networks (SSIDs)
- **Enable WLAN** - Activate a wireless network
- **Disable WLAN** - Deactivate a wireless network
- **Update WLAN Password** - Change wireless network password
### Switch & Port Management (2 tools)
- **List Port Profiles** - View configured switch port profiles
- **Get Switch Ports** - View port configuration and status for a specific switch
### Security & Firewall (1 tool)
- **List Firewall Rules** - View all configured firewall rules
### Traffic & Analytics (2 tools)
- **Traffic Statistics** - Network traffic stats (hourly/daily/monthly)
- **DPI Statistics** - Deep Packet Inspection and application usage data
### Alerts & Events (2 tools)
- **List Alerts** - View recent system alerts and alarms
- **List Events** - View recent network events and logs
### Guest Access (2 tools)
- **List Guest Vouchers** - View all guest access vouchers
- **Create Guest Voucher** - Generate new guest access vouchers with expiration
### Backup & Maintenance (1 tool)
- **Create Backup** - Initiate a controller configuration backup
## Installation
### Prerequisites
- Node.js 20.x or higher
- UniFi Network Controller (Cloud Gateway, Dream Machine, or self-hosted)
- UniFi admin credentials
### Install Dependencies
```bash
npm install
```
### Build the Server
```bash
npm run build
```
The compiled JavaScript will be output to the `dist/` directory.
## Configuration
Configure the server using environment variables:
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `UNIFI_URL` | UniFi controller URL | `https://192.168.1.1` | Yes |
| `UNIFI_USERNAME` | Admin username | `admin` | Yes |
| `UNIFI_PASSWORD` | Admin password | - | Yes |
| `UNIFI_SITE` | Site name/ID | `default` | No |
### Example Configuration
Create a `.env` file (not committed to git):
```bash
UNIFI_URL=https://192.168.16.254
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your_password_here
UNIFI_SITE=default
```
## Usage
### With Claude Desktop
Add to your Claude Desktop configuration file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"unifi": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/mcp-servers/unifi/dist/index.js"],
"env": {
"UNIFI_URL": "https://192.168.16.254",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "your_password_here",
"UNIFI_SITE": "default"
}
}
}
}
```
### Standalone Testing
Run the server directly for testing:
```bash
npm start
```
Or in development mode with auto-reload:
```bash
npm run dev
```
## Tool Reference
### Site Tools
#### `unifi_get_site_health`
Get overall site health and subsystem status scores.
**Parameters:** None
**Example Response:**
```json
[
{
"subsystem": "wan",
"status": "ok",
"num_user": 45,
"num_guest": 0
}
]
```
#### `unifi_get_traffic_stats`
Get network traffic statistics.
**Parameters:**
- `timeframe` (optional): `hourly`, `daily`, or `monthly`
#### `unifi_create_backup`
Initiate a controller configuration backup.
**Parameters:** None
### Device Tools
#### `unifi_list_devices`
List all UniFi devices with status and basic info.
**Parameters:**
- `type` (optional): Filter by device type (`uap`, `usw`, `ugw`, `udm`)
**Example Response:**
```json
[
{
"name": "Office AP",
"mac": "aa:bb:cc:dd:ee:ff",
"type": "uap",
"model": "U6-LR",
"ip": "192.168.1.10",
"state": "connected",
"uptime": "15d 6h 30m",
"clients": 12
}
]
```
#### `unifi_get_device`
Get detailed information about a specific device.
**Parameters:**
- `mac` (required): Device MAC address
#### `unifi_restart_device`
Restart a UniFi device.
**Parameters:**
- `mac` (required): Device MAC address
#### `unifi_locate_device`
Enable LED blink on a device for physical identification.
**Parameters:**
- `mac` (required): Device MAC address
### Client Tools
#### `unifi_list_clients`
List all connected network clients.
**Parameters:**
- `type` (optional): Filter by connection type (`all`, `wireless`, `wired`)
**Example Response:**
```json
[
{
"name": "iPhone",
"mac": "11:22:33:44:55:66",
"ip": "192.168.1.100",
"type": "wireless",
"signal": -45,
"uptime": "2d 4h 15m",
"tx_bytes": "1.2 GB",
"rx_bytes": "450 MB"
}
]
```
#### `unifi_get_client`
Get detailed information about a specific client.
**Parameters:**
- `mac` (required): Client MAC address
#### `unifi_block_client`
Block a client from network access.
**Parameters:**
- `mac` (required): Client MAC address
#### `unifi_unblock_client`
Unblock a previously blocked client.
**Parameters:**
- `mac` (required): Client MAC address
#### `unifi_reconnect_client`
Force a client to reconnect (kick and allow rejoin).
**Parameters:**
- `mac` (required): Client MAC address
### WLAN Tools
#### `unifi_list_networks`
List all configured networks and VLANs.
**Example Response:**
```json
[
{
"id": "507f1f77bcf86cd799439011",
"name": "Main LAN",
"purpose": "corporate",
"vlan": null,
"subnet": "192.168.1.1/24"
}
]
```
#### `unifi_list_wlans`
List all wireless networks (SSIDs).
**Example Response:**
```json
[
{
"id": "507f1f77bcf86cd799439012",
"name": "Home WiFi",
"enabled": true,
"security": "wpapsk"
}
]
```
#### `unifi_enable_wlan`
Enable a wireless network.
**Parameters:**
- `wlan_id` (required): WLAN ID from `list_wlans`
#### `unifi_disable_wlan`
Disable a wireless network.
**Parameters:**
- `wlan_id` (required): WLAN ID from `list_wlans`
#### `unifi_set_wlan_password`
Change the password for a wireless network.
**Parameters:**
- `wlan_id` (required): WLAN ID from `list_wlans`
- `password` (required): New password (8+ characters)
### Switch Tools
#### `unifi_list_port_profiles`
List all configured switch port profiles.
#### `unifi_get_switch_ports`
Get port configuration and status for a specific switch.
**Parameters:**
- `mac` (required): Switch MAC address
### Security Tools
#### `unifi_list_firewall_rules`
List all configured firewall rules.
### Analytics Tools
#### `unifi_get_dpi_stats`
Get Deep Packet Inspection statistics and application usage.
#### `unifi_list_alerts`
List recent system alerts.
**Parameters:**
- `limit` (optional): Number of alerts to return (default: 50)
#### `unifi_list_events`
List recent network events.
**Parameters:**
- `limit` (optional): Number of events to return (default: 50)
### Guest Access Tools
#### `unifi_list_vouchers`
List all guest access vouchers.
#### `unifi_create_voucher`
Create new guest access vouchers.
**Parameters:**
- `count` (required): Number of vouchers to create
- `expire_minutes` (required): Validity duration in minutes
- `note` (optional): Description/note for the vouchers
**Example:**
```json
{
"count": 5,
"expire_minutes": 1440,
"note": "Conference Day 1"
}
```
## Architecture
This MCP server is built with:
- **TypeScript** for type safety and modern JavaScript features
- **@modelcontextprotocol/sdk** for MCP protocol implementation
- **axios** for UniFi API communication
- **stdio transport** for seamless integration with MCP clients
## Limitations
This server provides **read-only access** for most configuration settings. While you can:
- Enable/disable WLANs
- Change WLAN passwords
- Block/unblock clients
- Restart devices
- Create backups
You **cannot** directly:
- Create new networks or VLANs
- Modify firewall rules
- Configure device settings
- Change DPI settings
- Modify switch port configurations
For advanced configuration changes, use the UniFi Network Controller web interface.
## Security Considerations
- **Never commit `.env` files** with credentials to version control
- Use **strong passwords** for UniFi admin accounts
- Consider **read-only admin accounts** if your controller supports them
- Enable **two-factor authentication** on your UniFi account
- Use **HTTPS** for controller connections when possible
- Store credentials securely using environment variables or secret management
## Troubleshooting
### Connection Issues
If you receive authentication errors:
1. Verify your `UNIFI_URL` is correct and accessible
2. Check that `UNIFI_USERNAME` and `UNIFI_PASSWORD` are correct
3. Ensure the user has admin privileges
4. Verify SSL certificate settings (the server disables certificate verification by default)
### Self-Signed Certificates
The server automatically accepts self-signed certificates. If you need to enforce certificate validation, modify the `httpsAgent` configuration in `src/index.ts`.
### Debug Mode
Enable detailed logging by running:
```bash
NODE_ENV=development npm start
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - See LICENSE file for details
## Related Projects
- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP documentation
- [UniFi Network Controller](https://ui.com/consoles) - UniFi hardware and software
- [Claude Desktop](https://claude.ai/desktop) - Desktop client supporting MCP
## Support
For issues, questions, or contributions, please open an issue on GitHub.
---
**Note:** This is an unofficial tool and is not affiliated with or endorsed by Ubiquiti Inc.
