UniFi

You can manage UniFi Network, Protect cameras, and Access doors through a dedicated MCP server that connects to the UniFi Cloud API. It provides secure OAuth access, multiple transport options, and deployment flexibility, so your AI assistant can perform network operations with natural language commands while keeping your credentials safe.

How to use

You interact with the UniFi MCP Server through an MCP client to issue natural language requests. Typical tasks include checking network health, listing devices and clients, controlling cameras, and performing actions on doors. The server supports both local (stdio) and remote (http) deployment modes, and uses OAuth 2.0 with PKCE for secure access. When you connect, you can begin phrases like: “Show me the status of my UniFi network” or “Unlock the front door for 10 seconds.” The MCP translates your request into actions against the UniFi Cloud API and returns results in natural language.

For local development, you can run the server directly on your machine and point your MCP client to the local process. For remote usage, deploy the HTTP server on a VPS or a hosting platform, enable HTTPS, and complete the OAuth flow to authorize access from Claude Desktop, Claude Mobile, or ChatGPT.

How to install

Prerequisites you need before installing are Node.js and npm. Ensure Node.js 20+ is available on your system.

Step 1: Clone the project and enter the directory.

git clone https://github.com/yourusername/unifi-mcp-server.git
cd unifi-mcp-server

Step 2: Install dependencies.

npm install

Step 3: Create the environment file from the example.

cop .env.example .env

Configuration and environment

Edit the environment file to configure credentials and server behavior. The key settings shown include your UniFi Cloud API key, server port, base URL, and optional OAuth password and API key.

# 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

Run and deployment options

Development mode (stdio transport for Claude Desktop) runs the server locally so you can test and iterate quickly.

npm run dev

Production deployment uses the HTTP transport with OAuth for remote access. Start the server in production mode to expose an HTTP endpoint and enable OAuth flows.

npm run start:http

If you prefer containerized deployment, you can run the server with Docker using Docker Compose.

docker-compose up -d

Claude Desktop configuration

Configure Claude Desktop to connect to the local MCP server by pointing it to the local runtime and supplying the UniFi API key in the environment.

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

Remote access and OAuth

To enable remote usage via Claude Mobile or ChatGPT, deploy the HTTP server on a public domain with HTTPS and complete the OAuth flow. You will use a server URL like https://your-domain.com and authorize with the appropriate client (claude-mobile or chatgpt) and scope unifi-api.

Server URL: https://your-domain.com
Client ID: claude-mobile or chatgpt
Scope: unifi-api

Deployment notes

Deployment can be done on Coolify, a VPS, or any hosting platform that supports Docker. Ensure you configure HTTPS with a valid TLS certificate and set the correct environment variables mentioned earlier. You can also run the server directly on your machine for testing before moving to production.

Security and maintenance

Use HTTPS in production to protect traffic. Rely on OAuth 2.0 with PKCE for secure authorization, and store tokens securely in Redis with TTL. You can also use an API key as an alternative for server-to-server access. If you need to rotate credentials, update the environment file and restart the server.

Troubleshooting

If you encounter API key issues, test connectivity to the UniFi Cloud API and verify your key in the environment. Ensure BASE_URL uses HTTPS and that redirect URIs match client configuration for OAuth.

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

For connection problems, verify API reachability, check firewall rules, and review logs from docker-compose.

docker-compose logs -f

API and endpoints

The server exposes endpoints to health checks, status, OAuth discovery and token exchange, as well as the MCP transport channel for messages.

Notes

This MCP server configuration supports both local and remote usage paths, with environment and startup commands shown above. Follow the installation steps in order, and adjust environment values to fit your domain and security needs.

Available tools

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

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

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

list_cameras

List all cameras

get_camera

Get camera details

set_camera_privacy

Toggle privacy mode

set_camera_recording

Set recording mode

list_doors

List all access doors

unlock_door

Temporarily unlock a door

lock_door

Lock a door