mjrestivo16/mcp-unifi

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:

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, 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:

[
  {
    "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 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:

{
  "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:

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 - 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.