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```bash
cp .env.example .env
Edit `.env`:```bash
# 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```bash
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:
- MCP client discovers OAuth endpoints via
/.well-known/oauth-authorization-server - Client initiates OAuth flow to
/authorizewith PKCE - User authenticates via Cloudflare Access (supports Entra ID, Google, etc.)
- Upon approval, client exchanges code for tokens at
/token - Client accesses
/mcpwith 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```bash
Install dependencies
npm install
Run with hot-reload
npm run dev
Check syntax
node --check server.js
```
License
MIT
