unifi-protect-mcp 0.1.2

UniFi Protect MCP Server

UniFi Protect MCP Server

MCP server exposing UniFi Protect tools for LLMs, agents, and automation platforms. Query cameras, events, smart detections, recordings, lights, sensors, and chimes -- with safe-by-default permissions and preview-before-confirm for all mutations.

Install

Claude Code (recommended)

The plugin installs the MCP server, an agent skill for tool discovery, and a guided setup command:

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-protect@unifi-plugins

Then run the interactive setup to configure your controller connection:

/unifi-protect:setup

This walks you through entering your controller host, credentials, and permission preferences — then writes everything to .claude/settings.json so it persists across sessions. If you already have the Network plugin configured on the same controller, the setup will detect and reuse those credentials. Restart Claude Code after setup to connect.

PyPI / Docker

# PyPI
uvx unifi-protect-mcp
# or: pip install unifi-protect-mcp

# Docker
docker pull ghcr.io/sirkirby/unifi-protect-mcp:latest

# From source
git clone https://github.com/sirkirby/unifi-mcp.git
cd unifi-mcp && uv sync

Configure

Set these environment variables (or create a .env file). If you used /unifi-protect:setup, this is already done.

# Server-specific variables (recommended)
UNIFI_PROTECT_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_PROTECT_USERNAME=admin         # Local admin username
UNIFI_PROTECT_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_PROTECT_API_KEY=             # UniFi API key (experimental — read-only, subset of tools)
# UNIFI_PROTECT_PORT=443             # Controller HTTPS port
# UNIFI_PROTECT_VERIFY_SSL=false     # SSL certificate verification

Fallback: The shared UNIFI_* variables (e.g., UNIFI_HOST) also work. The server checks for UNIFI_PROTECT_* first and falls back to UNIFI_* if the server-specific variable is not set. For single-controller setups, the shared variables are all you need.

Run

# stdio transport (default -- for Claude Desktop, LM Studio, etc.)
unifi-protect-mcp

# Docker
docker run -i --rm \
  -e UNIFI_PROTECT_HOST=192.168.1.1 \
  -e UNIFI_PROTECT_USERNAME=admin \
  -e UNIFI_PROTECT_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-protect-mcp:latest

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "unifi-protect": {
      "command": "uvx",
      "args": ["unifi-protect-mcp"],
      "env": {
        "UNIFI_PROTECT_HOST": "192.168.1.1",
        "UNIFI_PROTECT_USERNAME": "admin",
        "UNIFI_PROTECT_PASSWORD": "your-password"
      }
    }
  }
}

Features

• Cameras -- list, inspect, snapshot, RTSP streams, PTZ control, settings, recording toggle, reboot
• Events -- query historical events, smart detections (person/vehicle/animal/package), thumbnails
• Real-time streaming -- websocket event buffer with MCP resource subscriptions and polling
• Recordings -- status, availability, clip export with timelapse support
• Devices -- lights (brightness, PIR sensitivity), sensors (temperature, humidity, motion), chimes (volume, trigger)
• Liveviews -- list and inspect multi-camera layouts
• System -- NVR info, health metrics, firmware status, connected viewers

Documentation

• Configuration -- Full env var reference, YAML config, Protect-specific options
• Permissions -- Permission system, category defaults, how to enable mutations
• Tool Catalog -- All 34 tools organized by category
• Event Streaming -- Real-time event architecture, MCP resources, polling
• Troubleshooting -- Connection issues, SSL, missing tools

Development

cd apps/protect
make test         # Run tests
make lint         # Lint
make format       # Format
make manifest     # Regenerate tools_manifest.json
make pre-commit   # All of the above

See the root CONTRIBUTING.md for the full monorepo workflow.

License

MIT