UniFi MCP Server

A Model Context Protocol server for managing UniFi networks through Claude Desktop or other MCP clients.

Features

• 18 MCP Tools - Comprehensive network management capabilities

• OAuth 2.1 + PKCE - Secure authentication with Cloudflare Access

• API Key Authentication - Uses official UniFi API with X-API-KEY

• MCP 2025-11-25 Compliant - Full specification compliance

• Remote Ready - Designed for access via Cloudflare Tunnel

Quick Start

1. Generate UniFi API Key

In your UniFi Controller/UDM:

• Go to Settings → Control Plane → Integrations

• Click Generate API Key

• Copy the key

2. Configure Environment

cp .env.example .env

Edit .env:

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

# Cloudflare Access for SaaS (OAuth identity provider)
CF_ACCESS_TEAM=your-team-name
CF_CLIENT_ID=your-client-id
CF_CLIENT_SECRET=your-client-secret

# UniFi Controller
UNIFI_HOST=192.168.1.1
UNIFI_API_KEY=your-api-key-from-step-1

3. Start with Docker

docker compose up -d

4. Configure Cloudflare

1. Create a Cloudflare Tunnel pointing to your server

2. Create an Access for SaaS application in Zero Trust:

   • Protocol: OIDC

   • Redirect URL: https://your-domain.com/callback

3. Connect with Claude Desktop using your tunnel URL

Available Tools

Client Management

Device Management

Network Configuration

Monitoring

Architecture

Claude Desktop
      ↓
Cloudflare Tunnel (secure tunnel)
      ↓
UniFi MCP Server (OAuth 2.1 + MCP)
      ↓
UniFi Controller/UDM (X-API-KEY)

Authentication Flow

This server implements OAuth 2.1 with Cloudflare Access as the identity provider:

1. MCP client discovers OAuth endpoints via /.well-known/oauth-authorization-server

2. Client initiates OAuth flow to /authorize with PKCE

3. User authenticates via Cloudflare Access (supports Entra ID, Google, etc.)

4. Upon approval, client exchanges code for tokens at /token

5. Client accesses /mcp with Bearer token

OAuth Endpoints

Configuration

Security

• OAuth 2.1 + PKCE - Secure token exchange

• Cloudflare Tunnel - No direct IP exposure

• Cloudflare Access - Identity verification at the edge

• API Key Auth - No passwords stored, scoped access

Recommended WAF Rules

Consider blocking non-essential paths:

• Allow: /.well-known/*, /register, /authorize, /callback, /token, /mcp

• Block or protect: /, /health

Tech Stack

• Node.js 22 with ES Modules

• @modelcontextprotocol/sdk

• Express.js

• Docker with Alpine Linux

Development

# Install dependencies
npm install

# Run with hot-reload
npm run dev

# Check syntax
node --check server.js

License

MIT