unifi-protect-mcp 0.1.0

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

# PyPI (recommended)
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):

# 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=             # Official UniFi API key (dual auth)
# 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