UniFi MCP Server

Control your UniFi network via AI. 2-tool design powered by OpenAPI spec — works with UniFi Cloud API or local Dream Machine.

What it does

• Query devices, clients, network stats
• Manage WiFi, VLANs, firewall rules
• Create network configurations
• Monitor network health

Quick Setup (5 minutes)

1. Get your UniFi API Key

1. Go to account.ui.com
2. Sign in → Settings → API Keys
3. Create new key → copy it

2. Run with npx (no install)

UNIFI_API_TYPE=cloud-ea UNIFI_API_KEY=your-key-here npx @bakhshb/unifi-mcp

Or create a .env file:

UNIFI_API_TYPE=cloud-ea
UNIFI_API_KEY=your-key-here

Then run:

npx @bakhshb/unifi-mcp

3. Connect to Claude/OpenClaw

OpenClaw (~/.openclaw/openclaw.json):

{
  "mcp": {
    "servers": {
      "unifi": {
        "command": "npx",
        "args": ["@bakhshb/unifi-mcp"],
        "env": {
          "UNIFI_API_TYPE": "cloud-ea",
          "UNIFI_API_KEY": "your-key-here"
        }
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["@bakhshb/unifi-mcp"],
      "env": {
        "UNIFI_API_TYPE": "cloud-ea",
        "UNIFI_API_KEY": "your-key-here"
      }
    }
  }
}

Local Dream Machine Setup

Your local UniFi controller (Dream Machine, etc.) also supports API keys, just like the cloud API. Generate an API key in your controller settings:

1. Go to your UniFi Controller → Settings → API Keys
2. Create a new key for local access
3. Use the same env vars as cloud, but with UNIFI_API_TYPE=local

UNIFI_API_TYPE=local
UNIFI_API_KEY=your-local-api-key
UNIFI_LOCAL_HOST=192.168.1.1
UNIFI_LOCAL_VERIFY_SSL=false

Or in openclaw.json:

{
  "mcp": {
    "servers": {
      "unifi": {
        "command": "npx",
        "args": ["@bakhshb/unifi-mcp"],
        "env": {
          "UNIFI_API_TYPE": "local",
          "UNIFI_API_KEY": "your-local-api-key",
          "UNIFI_LOCAL_HOST": "192.168.1.1",
          "UNIFI_LOCAL_VERIFY_SSL": "false"
        }
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | UNIFI_URL | Yes | - | Your UniFi controller URL (e.g., https://192.168.1.1 or https://api.ui.com for cloud) | | UNIFI_API_KEY | Yes* | - | Your API key (required if not using username/password) | | UNIFI_USERNAME | Yes | - | UniFi username (required if not using API key) | | UNIFI_PASSWORD | Yes | - | UniFi password (*required if not using API key) | | UNIFI_SITE_ID | No | default | Your UniFi site identifier | | UNIFI_TIMEOUT | No | 30000 | Request timeout in milliseconds |

Note: Set either UNIFI_API_KEY OR (UNIFI_USERNAME + UNIFI_PASSWORD).

Note: For local mode, you can also use session cookies (UNIFI_SESSION_COOKIE + UNIFI_CSRF_TOKEN) instead of API key, but API key is simpler.

API Modes Explained

UniFi MCP supports three connection modes, set via UNIFI_API_TYPE:

| Mode | When to use | Auth required | Rate limit | |------|-------------|---------------|------------| | local | Your Dream Machine / UDM Pro SE on the LAN | API key | None | | cloud-v1 | Remote management via Ubiquiti cloud (stable) | API key | 10,000 req/min | | cloud-ea | Remote management via Ubiquiti cloud (Early Access) | API key | 100 req/min |

local — Connect directly to your UniFi controller on the local network. Full access, no external traffic, no rate limits. Requires UNIFI_LOCAL_HOST.

cloud-v1 — Stable cloud API hosted at api.ui.com. Backward compatible with long-term support. Higher rate limit but core feature set only.

cloud-ea — Early Access cloud API at api.ui.com. Newer features before they land in v1, but lower rate limit and may still evolve. The Site Manager API and some newer endpoints live here first.

Which to choose?

• Home lab / local network → local (your UDM Pro SE)
• Remote management, production stability → cloud-v1
• Remote management, want latest features → cloud-ea

Commands

unifi-api

Execute any UniFi Integration API call. Examples:

• unifi-api with path="/v2/sites" → list all sites
• unifi-api with path="/v1/sites/{siteId}/devices" and pathParams={siteId:"default"} → get devices
• unifi-api with path="/v1/sites/{siteId}/clients" and pathParams={siteId:"default"} → get clients

unifi-api-schema

Discover available Integration API operations:

• No args → list all tags/operations
• tag="sites" → operations for sites
• path="/v1/sites/{siteId}/devices" → details for that path

unifi-legacy-client-stats

Get per-client bandwidth statistics from the legacy controller API (/api/s/{site}/stat/sta). This endpoint is separate from the Integration API and returns real-time tx/rx bytes and rates per client.

Why a separate tool? The legacy controller API is not covered by the UniFi OpenAPI spec (beezly/unifi-apis). It exists on the same controller but uses different paths (/proxy/network/api/s/) and returns bandwidth data (tx_bytes, rx_bytes, tx_rate, rx_rate) unavailable in the Integration API.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | site | string | "default" | Site name or ID |

Example response:

{
  "success": true,
  "message": "Legacy client stats: 2 active clients on site 'default'",
  "data": {
    "count": 2,
    "site": "default",
    "clients": [
      {
        "hostname": "iPhone",
        "ip": "192.168.1.100",
        "mac": "aa:bb:cc:dd:ee:ff",
        "network": "Home",
        "vlan": 1,
        "is_wired": false,
        "tx_bytes": 1234567890,
        "tx_bytes_formatted": "1.15 GB",
        "rx_bytes": 987654321,
        "rx_bytes_formatted": "941.8 MB",
        "tx_rate_bps": 1500,
        "tx_rate_formatted": "1.5 Kbps",
        "rx_rate_bps": 800,
        "rx_rate_formatted": "800 bps",
        "uptime": 3600,
        "uptime_formatted": "1h 0m",
        "signal": -50,
        "essid": "MyWiFi",
        "ap_name": "UDM-Pro"
      },
      {
        "hostname": "laptop",
        "ip": "192.168.1.50",
        "mac": "11:22:33:44:55:66",
        "network": "Home",
        "vlan": 1,
        "is_wired": true,
        "tx_bytes": 50000000,
        "tx_bytes_formatted": "47.7 MB",
        "rx_bytes": 100000000,
        "rx_bytes_formatted": "95.4 MB",
        "tx_rate_bps": 0,
        "tx_rate_formatted": "0 B/s",
        "rx_rate_bps": 0,
        "rx_rate_formatted": "0 B/s",
        "uptime": 7200,
        "uptime_formatted": "2h 0m",
        "ap_name": "Switch"
      }
    ]
  }
}

Troubleshooting

"API key required" → Set UNIFI_API_KEY in your environment

"Connection refused" → Check UNIFI_LOCAL_HOST for local mode

SSL errors → Set UNIFI_LOCAL_VERIFY_SSL=false for local

Architecture

Token savings: Traditional UniFi MCP servers cost ~45,000–60,000 tokens per session. The 2-tool + 1-legacy approach costs ~500–1,500 tokens for the Integration API, plus ~200 tokens for the legacy stats tool — a ~97% reduction.

| Approach | Tools | Token Cost | Coverage | |----------|-------|------------|----------| | enuno/unifi-mcp-server (explicit) | 148 | ~45,000–60,000 | Fixed | | sirkirby/unifi-mcp (multi-product) | ~82 | ~25,000–35,000 | Network + Protect + Access + Drive | | This server (2-tool + 1-legacy) | 3 tools | ~700–1,700 | 44+ Integration API ops + legacy stats |

• 3 tools instead of 148 explicit tools → ~97% less context overhead
• 2 generic tools for Integration API (OpenAPI spec-driven, dynamically scales with API surface)
• 1 legacy tool for bandwidth stats (not in OpenAPI spec, controller-specific)
• Inspired by @dokploy/mcp (tacticlaunch/dokploy-mcp) — first MCP server to demonstrate the 2-tool OpenAPI pattern, covering 463 Dokploy operations in ~500 tokens
• OpenAPI specs from beezly/unifi-apis (which traces its API research lineage to sirkirby/unifi-mcp)

License

MIT License