UniFi MCP Server
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
npm install
Build the Server
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):
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
{
"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:
npm start
Or in development mode with auto-reload:
npm run dev
Tool Reference
Site Tools
unifi_get_site_health
Get overall site health and subsystem status scores.
Parameters: None
Example Response:
[
{
"subsystem": "wan",
"status": "ok",
"num_user": 45,
"num_guest": 0
}
]
unifi_get_traffic_stats
Get network traffic statistics.
Parameters:
timeframe(optional):hourly,daily, ormonthly
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:
[
{
"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:
[
{
"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:
[
{
"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:
[
{
"id": "507f1f77bcf86cd799439012",
"name": "Home WiFi",
"enabled": true,
"security": "wpapsk"
}
]
unifi_enable_wlan
Enable a wireless network.
Parameters:
wlan_id(required): WLAN ID fromlist_wlans
unifi_disable_wlan
Disable a wireless network.
Parameters:
wlan_id(required): WLAN ID fromlist_wlans
unifi_set_wlan_password
Change the password for a wireless network.
Parameters:
wlan_id(required): WLAN ID fromlist_wlanspassword(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 createexpire_minutes(required): Validity duration in minutesnote(optional): Description/note for the vouchers
Example:
{
"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
.envfiles 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:
- Verify your
UNIFI_URLis correct and accessible - Check that
UNIFI_USERNAMEandUNIFI_PASSWORDare correct - Ensure the user has admin privileges
- 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:
NODE_ENV=development npm start
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - See LICENSE file for details
Related Projects
- Model Context Protocol - Official MCP documentation
- UniFi Network Controller - UniFi hardware and software
- Claude 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.