# UniFi MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) 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:
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](https://github.com/modelcontextprotocol/typescript-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
