# UniFi MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](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.