Unifi MCP Server

UniFi MCP

Leverage agents and agentic AI workflows to manage your UniFi deployment.

Servers

Cloud Relay

The relay bridges your local MCP servers to a Cloudflare Worker, letting cloud agents access your UniFi tools without exposing local ports. Supports multi-location with annotation-based fan-out for read-only tools. Deploy the worker with npm install -g unifi-mcp-worker && unifi-mcp-worker install, then see the relay README for connecting your local servers.

What is this?

UniFi MCP is a collection of Model Context Protocol servers that let AI assistants and automation tools interact with Ubiquiti UniFi controllers. Each server targets a specific UniFi application (Network, Protect, Access) and exposes its functionality as MCP tools — queryable, composable, and safe by default.

Quick Start

Claude Code (recommended)

Install via the plugin marketplace — includes the MCP server, an agent skill, and guided setup:

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-network@unifi-plugins
/unifi-network:setup

Repeat for Protect or Access if needed:

/plugin install unifi-protect@unifi-plugins
/plugin install unifi-access@unifi-plugins

Each plugin's /setup command walks you through connecting to your controller and configuring permissions.

Other MCP clients

Run the servers directly:

uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unifi-network": {
      "command": "uvx",
      "args": ["unifi-network-mcp@latest"],
      "env": {
        // Server-specific vars take priority; UNIFI_* is the fallback
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_USERNAME": "admin",
        "UNIFI_NETWORK_PASSWORD": "your-password"
      }
    },
    "unifi-protect": {
      "command": "uvx",
      "args": ["unifi-protect-mcp@latest"],
      "env": {
        "UNIFI_PROTECT_HOST": "192.168.1.1",
        "UNIFI_PROTECT_USERNAME": "admin",
        "UNIFI_PROTECT_PASSWORD": "your-password"
      }
    },
    "unifi-access": {
      "command": "uvx",
      "args": ["unifi-access-mcp@latest"],
      "env": {
        "UNIFI_ACCESS_HOST": "192.168.1.1",
        "UNIFI_ACCESS_USERNAME": "admin",
        "UNIFI_ACCESS_PASSWORD": "your-password"
      }
    }
  }
}

Tip: If all servers connect to the same controller, you can use the shared UNIFI_HOST / UNIFI_USERNAME / UNIFI_PASSWORD variables instead of repeating them per server.

Usage Examples

Once connected, just ask your AI agent in natural language:

Network

"Show me all clients on the Guest VLAN with their signal strength and data usage" "Create a firewall rule that blocks IoT devices from reaching the internet between midnight and 6 AM" "Audit my firewall policies — are there any redundant or conflicting rules?"

Protect

"List all cameras that detected motion in the last hour" "Show me smart detection events from the front door camera today — people and vehicles only"

Access

"Who badged into the office today? Show me a timeline of all door access events" "Create a visitor pass for John Smith with access to the main entrance tomorrow 9-5"

Cross-Product (requires relay for full experience)

"Show me everything that happened at the front entrance in the last hour" — correlates Network clients, Protect camera events, and Access badge scans in a single timeline "A switch went offline at 2 AM — was there physical activity nearby?"

All mutations use a preview-then-confirm flow — you see exactly what will change before anything is applied.

Configuration

Set these environment variables (or use a .env file):

Multi-controller setups

Each server supports its own prefixed environment variables that take priority over the shared UNIFI_* variables. This lets you point the Network and Protect servers at different controllers (or different credentials) while keeping a single .env file:

Single controller? Just set the shared UNIFI_* variables -- all servers will use them. Server-specific variables are only needed when the servers talk to different controllers or use different credentials.

For the full configuration reference including permissions, transports, and advanced options, see the Network server docs, Protect server docs, or Access server docs.

Agent Skills

Each plugin ships with agent skills that go beyond raw tool access — they teach agents how to perform common tasks effectively:

Skills include reference documentation (device states, alarm types, firewall schemas, event catalogs) and Python scripts for deterministic operations (auditing, config export/diff, template application).

Architecture

This is a monorepo with shared packages:

apps/
  network/          # UniFi Network MCP server (stable, 166 tools)
  protect/          # UniFi Protect MCP server (beta, 38 tools)
  access/           # UniFi Access MCP server (beta, 29 tools)
packages/
  unifi-core/       # Shared UniFi connectivity (auth, detection, retry)
  unifi-mcp-shared/ # Shared MCP patterns (permissions, tools, diagnostics, config)
  unifi-mcp-relay/  # Cloud relay sidecar (bridges local servers to Cloudflare Worker)
plugins/
  unifi-network/    # Claude Code plugin: MCP server + agent skills + setup
  unifi-protect/    # Claude Code plugin: MCP server + agent skills + setup
  unifi-access/     # Claude Code plugin: MCP server + setup
skills/
  _shared/          # Shared utilities for skill scripts (MCP client, config)
docs/               # Ecosystem-level documentation

Each server in apps/ is an independent Python package that depends on the shared packages. The shared packages ensure consistent behavior across all servers — same permission model, same confirmation flow, same lazy tool loading.

See docs/ARCHITECTURE.md for details.

Contributing

See CONTRIBUTING.md for the development workflow, including how to work with the monorepo, run tests, and submit PRs.

License

MIT