UniFi 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

Tool	Description
list_clients	List all connected devices
get_client	Get details for a specific client by MAC
search_devices	Search by name, IP, or MAC
block_client	Block a device from the network
unblock_client	Unblock a device
reconnect_client	Force a client to reconnect
list_blocked_clients	List blocked devices

Device Management

Tool	Description
list_devices	List all UniFi devices (APs, switches, gateways)
list_access_points	List access points with status
restart_device	Restart an AP or switch

Network Configuration

Tool	Description
list_networks	List VLANs and subnets
list_wlans	List wireless SSIDs
list_port_forwards	List port forwarding rules

Monitoring

Tool	Description
get_network_health	Network health statistics
list_events	Recent network events
list_alarms	Active and recent alarms

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

Endpoint	Description
/.well-known/oauth-authorization-server	Authorization server metadata
/.well-known/oauth-protected-resource/mcp	Protected resource metadata (RFC 9728)
/authorize	Authorization endpoint (auto-registers clients)
/token	Token endpoint
/register	Dynamic client registration
/callback	Cloudflare OAuth callback

Configuration

Variable	Required	Description
PORT	No	Server port (default: 3000)
BASE_URL	Yes	Public URL for OAuth redirects
CF_ACCESS_TEAM	Yes	Cloudflare Access team name
CF_CLIENT_ID	Yes	From Access for SaaS app
CF_CLIENT_SECRET	Yes	From Access for SaaS app
UNIFI_HOST	Yes	UniFi controller IP
UNIFI_PORT	No	Controller port (default: 443)
UNIFI_API_KEY	Yes	API key from UniFi
UNIFI_SITE	No	Site name (default: "default")

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