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

Quick Start

1. Get Your UniFi Cloud API Key

Go to UniFi Site Manager
Navigate to API section from the left navigation
Click "Create API Key"
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:

Deploy to your VPS or Coolify
Configure your domain with HTTPS
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

Create new application from Git repository
Set environment variables in Coolify dashboard
Configure your domain with HTTPS
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