Skip to main content
Glama
UniFi MCP Server

UniFi MCP Server

by vandreus

UniFi MCP Server

A Model Context Protocol (MCP) server for comprehensive UniFi Network Management via the UniFi Cloud API. This server enables AI assistants like Claude to manage your UniFi infrastructure through natural language.

Features

  • UniFi Cloud API Integration - Full access to api.ui.com for remote management

  • OAuth 2.0 Authentication - Secure access with PKCE support for Claude Desktop, Claude Mobile, ChatGPT, and more

  • Multi-Transport Support - SSE and Streamable HTTP for flexible deployment

  • Complete UniFi Ecosystem - Network, Protect (cameras), and Access (doors) management

  • Production Ready - Docker support, Redis for token storage, Coolify/VPS deployment

Related MCP server: UniFi Network MCP Server

Quick Start

1. Get Your UniFi Cloud API Key

  1. Go to UniFi Site Manager

  2. Navigate to API section from the left navigation

  3. Click "Create API Key"

  4. Copy the generated key

2. Installation

# Clone the repository
git clone https://github.com/yourusername/unifi-mcp-server.git
cd unifi-mcp-server

# Install dependencies
npm install

# Create environment file
cp .env.example .env

3. Configuration

Edit .env with your settings:

# Required: Your UniFi Cloud API Key
UNIFI_API_KEY=zjWD6zwI55loIpMLLcjDDvRTCuVnVyHA2

# Server settings
PORT=3000
BASE_URL=https://your-domain.com

# OAuth password for authorization (optional but recommended)
OAUTH_PASSWORD=your_secure_password

# API Key for direct access (optional)
API_KEY=your_api_key

4. Run the Server

Development (stdio mode for Claude Desktop):

npm run dev

Production (HTTP server with OAuth):

npm run start:http

Docker:

docker-compose up -d

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unifi": {
      "command": "node",
      "args": ["/path/to/unifi-mcp-server/src/index.js"],
      "env": {
        "UNIFI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Remote Access (Claude Mobile / ChatGPT)

For remote access, deploy the HTTP server and connect via OAuth:

  1. Deploy to your VPS or Coolify

  2. Configure your domain with HTTPS

  3. Connect using the OAuth flow:

    • Server URL: https://your-domain.com

    • Client ID: claude-mobile or chatgpt

    • Scope: unifi-api

Available Tools

Network & System

Tool

Description

unifi_health

Check UniFi Cloud API connectivity

get_system_status

Comprehensive system status overview

list_hosts

List all UniFi OS consoles

list_sites

List all network sites

get_isp_metrics

Get ISP performance metrics

Devices

Tool

Description

list_all_devices

List all UniFi devices

get_device

Get device details

locate_device

Flash LEDs to locate a device

restart_device

Restart a device

find_device_by_mac

Search by MAC address

get_offline_devices

List offline devices

Clients

Tool

Description

list_all_clients

List all connected clients

block_client

Block a client from network

unblock_client

Unblock a client

reconnect_client

Force reconnect a client

find_client_by_name

Search clients by name

get_client_bandwidth_summary

Bandwidth usage analysis

UniFi Protect (Cameras)

Tool

Description

list_cameras

List all cameras

get_camera

Get camera details

set_camera_privacy

Toggle privacy mode

set_camera_recording

Set recording mode

UniFi Access (Doors)

Tool

Description

list_doors

List all access doors

unlock_door

Temporarily unlock a door

lock_door

Lock a door

Example Usage

Once connected, you can use natural language:

  • "Show me the status of my UniFi network"

  • "List all offline devices"

  • "Who's using the most bandwidth?"

  • "Block the device with MAC XX:XX:XX:XX:XX:XX"

  • "Unlock the front door for 10 seconds"

  • "Turn on privacy mode for the garage camera"

Deployment

Coolify

  1. Create new application from Git repository

  2. Set environment variables in Coolify dashboard

  3. Configure your domain with HTTPS

  4. Deploy!

Docker Compose

# Set environment variables
export UNIFI_API_KEY=your_key
export OAUTH_PASSWORD=your_password
export BASE_URL=https://your-domain.com

# Start services
docker-compose up -d

Manual VPS

# Install Node.js 20+
# Clone repository
# Install dependencies: npm install
# Set up systemd service or PM2
# Configure reverse proxy (nginx/caddy) with SSL

API Endpoints

Endpoint

Description

GET /health

Health check

GET /status

Server status

GET /.well-known/oauth-authorization-server

OAuth discovery

GET /oauth/authorize

OAuth authorization

POST /oauth/token

Token exchange

GET /sse

SSE transport

POST /mcp/messages

MCP messages (authenticated)

Security

  • HTTPS Required - Always use HTTPS in production

  • OAuth 2.0 + PKCE - Secure authorization flow

  • API Key Authentication - Alternative for server-to-server

  • Password Protection - Optional OAuth authorization password

  • Redis Token Storage - Secure token management with TTL

Troubleshooting

API Key Issues

# Test your API key
curl -H "X-API-Key: YOUR_KEY" https://api.ui.com/v1/hosts

OAuth Issues

  • Check OAUTH_PASSWORD is set correctly

  • Verify BASE_URL uses HTTPS

  • Ensure redirect URIs match client configuration

Connection Issues

  • Verify UniFi Cloud API is accessible

  • Check firewall rules for port 3000

  • Review container logs: docker-compose logs -f

License

MIT License - See LICENSE file for details.

Contributing

Pull requests welcome! Please ensure:

  • Tests pass

  • Documentation updated

  • Code follows existing style

Available Tools

39 tools
block_clientD

Inputs: no named parameters.

find_camera_by_nameD

Inputs: no named parameters.

find_client_by_macD

Inputs: no named parameters.

find_client_by_nameD

Inputs: no named parameters.

find_device_by_macD

Inputs: no named parameters.

find_devices_by_nameD

Inputs: no named parameters.

find_door_by_nameD

Inputs: no named parameters.

get_cameraD

Inputs: no named parameters.

get_cameras_status_summaryD

Inputs: no named parameters.

get_client_bandwidth_summaryD

Inputs: no named parameters.

get_clients_for_hostD

Inputs: no named parameters.

get_clients_for_siteD

Inputs: no named parameters.

get_deviceD

Inputs: no named parameters.

get_devices_for_hostD

Inputs: no named parameters.

get_devices_for_siteD

Inputs: no named parameters.

get_doorD

Inputs: no named parameters.

get_doors_status_summaryD

Inputs: no named parameters.

get_hostD

Inputs: no named parameters.

get_isp_metricsD

Inputs: no named parameters.

get_offline_devicesD

Inputs: no named parameters.

get_sites_for_hostD

Inputs: no named parameters.

get_system_statusD

Inputs: no named parameters.

get_wired_clientsD

Inputs: no named parameters.

get_wireless_clientsD

Inputs: no named parameters.

list_all_clientsD

Inputs: no named parameters.

list_all_devicesD

Inputs: no named parameters.

list_camerasD

Inputs: no named parameters.

list_doorsD

Inputs: no named parameters.

list_hostsD

Inputs: no named parameters.

list_sitesD

Inputs: no named parameters.

locate_deviceD

Inputs: no named parameters.

lock_doorD

Inputs: no named parameters.

reconnect_clientD

Inputs: no named parameters.

restart_deviceD

Inputs: no named parameters.

set_camera_privacyD

Inputs: no named parameters.

set_camera_recordingD

Inputs: no named parameters.

unblock_clientD

Inputs: no named parameters.

unifi_healthD

Inputs: no named parameters.

unlock_doorD

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    D1.7/5.0

    Scored across 39 tools

    Disambiguation3/5

    The tools are mostly distinct by resource type (client, device, camera, door, host, site) and action (get, find, list, control), but there is some overlap between 'find' and 'get' operations (e.g., find_client_by_mac vs. get_client_bandwidth_summary) that could cause confusion about which to use for specific queries. The lack of descriptions exacerbates this ambiguity, though the naming patterns help differentiate core purposes.

    Naming Consistency4/5

    Tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., get_client_bandwidth_summary, list_all_devices, block_client). Minor deviations exist, such as 'unifi_health' lacking a verb and 'locate_device' using a less common verb, but overall the naming is predictable and readable across the set.

    Tool Count2/5

    With 39 tools, the count is excessive for the UniFi management domain, leading to a bloated interface that may overwhelm agents. While UniFi covers multiple resource types (clients, devices, cameras, doors, hosts, sites), the tool set could be consolidated (e.g., merging similar 'find' and 'get' operations) without losing functionality, making it feel heavy and inefficient for typical agent workflows.

    Completeness4/5

    The tool set provides comprehensive coverage for UniFi network and device management, including CRUD-like operations (e.g., block/unblock clients, lock/unlock doors, set camera settings) and status monitoring across resources. Minor gaps might exist, such as detailed configuration updates for devices or advanced site settings, but core lifecycle actions and queries are well-represented for the inferred domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.
      41
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to manage UniFi network infrastructure through 50+ tools covering devices, clients, networks, WiFi, firewall rules, and guest access using the official UniFi Network API.
      52
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive management of UniFi Network infrastructure through 24 tools for monitoring and controlling devices, clients, wireless networks, security, and guest access. Supports network administration tasks like device restarts, client blocking, WLAN configuration, and backup creation.
      14 npm
      MIT
    • A
      license
      C
      quality
      A
      maintenance
      Enables AI agents to manage UniFi network infrastructure via the Model Context Protocol, supporting device management, network configuration, security, and QoS through local or cloud APIs.
      71
      43 npm
      493 PyPI
      369
      Apache 2.0