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

Devices

Clients

UniFi Protect (Cameras)

UniFi Access (Doors)

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

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