UniFi Network MCP Server

A Model Context Protocol (MCP) server for the UniFi Network API. Manage your UniFi network infrastructure through AI assistants like Claude.

Quick Install

curl -fsSL https://raw.githubusercontent.com/Ruashots/unifi-network-mcp/master/install.sh | bash

This will:

• Clone the repository to ~/.local/share/unifi-network-mcp
• Install dependencies and build
• Prompt for your UniFi Console URL and API key
• Configure Claude Code automatically

Other commands:

# Reconfigure credentials
~/.local/share/unifi-network-mcp/install.sh --reconfigure

# Uninstall
~/.local/share/unifi-network-mcp/install.sh --uninstall

Features

50+ tools covering the complete UniFi Network API:

• Sites - List all sites accessible to the API key
• Devices - List, get statistics, adopt, restart, locate devices
• Clients - View connected clients, authorize guest access
• Networks - Full CRUD for network configurations
• WiFi - Create and manage SSIDs with security settings
• Hotspot Vouchers - Generate and manage guest vouchers
• Firewall Zones - Organize networks into security zones
• ACL Rules - Create and manage firewall rules with scheduling
• Traffic Matching Lists - IP groups, port groups, domains, apps, regions

Prerequisites

• Node.js 18+
• UniFi Console with Network application (UniFi OS Console, Cloud Key, or self-hosted)
• UniFi API key (Site Admin or Super Admin role)
• jq (for automatic Claude Code configuration)

Getting a UniFi API Key

1. Log into your UniFi Console
2. Click your profile icon (bottom left)
3. Go to API section
4. Click Create API Key
5. Copy the key (only shown once)

Note: Your API key inherits your user permissions. Use a Site Admin or Super Admin account for full access.

Manual Installation

# Clone the repository
git clone https://github.com/Ruashots/unifi-network-mcp.git
cd unifi-network-mcp

# Install dependencies
npm install

# Build
npm run build

Usage

Claude Code CLI

claude mcp add unifi-network \
  --transport stdio \
  -e UNIFI_API_KEY="your-api-key" \
  -e UNIFI_BASE_URL="https://your-console-ip" \
  -- node /path/to/unifi-network-mcp/dist/index.js

Scope options:

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "unifi-network": {
      "command": "node",
      "args": ["/path/to/unifi-network-mcp/dist/index.js"],
      "env": {
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_BASE_URL": "https://your-console-ip"
      }
    }
  }
}

Environment Variables

Available Tools

Application

Sites

Devices

Clients

Networks

WiFi

Hotspot Vouchers

Firewall Zones

ACL Rules (Firewall)

Traffic Matching Lists

Supporting Resources

Example Prompts

Once configured, use natural language:

"List all my UniFi sites"

"What devices are connected to my network?"

"Create a guest WiFi network with WPA3 security"

"Show me which clients are currently connected"

"Create 10 hotspot vouchers valid for 24 hours"

"Block traffic from the IoT network to the main network"

"Restart the access point in the living room"

"What's the current status of my UDM Pro?"

Development

npm install      # Install dependencies
npm run dev      # Run in development mode
npm run build    # Build for production
npm run watch    # Watch mode

API Endpoint

The MCP server connects to the UniFi Network Integration API at:

{UNIFI_BASE_URL}/proxy/network/integration/v1/...

This is the official public API introduced in UniFi Network 9.0+.

Security

• Keep API keys secure and never commit them to version control
• Use environment variables for sensitive configuration
• API keys inherit user permissions - use least privilege principle
• Consider creating a dedicated API user for automation

License

MIT

Links

• UniFi Developer Portal
• UniFi Network API Documentation
• Model Context Protocol