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

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