UniFi Protect MCP — Claude Code MCP server: setup and usage
Connects UniFi Protect hardware to AI assistants. It lets models inspect camera events, search detections, and tweak device settings directly from the prompt.
claude mcp add --env UNIFI_HOST=<UNIFI_HOST> --env UNIFI_USERNAME=<UNIFI_USERNAME> --env UNIFI_PASSWORD=<UNIFI_PASSWORD> --env UNIFI_API_KEY=<UNIFI_API_KEY> --env UNIFI_PORT=<UNIFI_PORT> --transport stdio protect -- uvx unifi-protect-mcpWhat UniFi Protect MCP does
This server links UniFi Protect deployments to coding assistants like Claude Code and Codex. It tracks cameras and environmental sensors. The agent can pull recorded video clips or search for license plates and identified faces.
Read operations stay safe by default. Any change to device settings or floodlights requires confirmation after a preview. When the controller rejects a partial update, the server returns the parameters that took effect so you can review the state.
Running the server requires Python 3.13+. Without UNIFI_PROTECT_API_KEY, adjusting microphone volume or camera HDR fails before writing to hardware. The process can also start in setup mode without touching the local network if host credentials are not yet configured.
What it helps with
- retrieve smart detection records for vehicles and people across cameras
- inspect offline cameras and unstable connection statuses
- locate recorded video segments within a designated time window
- adjust floodlight brightness levels and PIR sensor durations
Example prompts for the agent
- List all camera smart detections from the front yard today.
- Find driveway recordings between 2 AM and 5 AM last night.
- Check if any security sensors triggered alerts over the last six hours.
How to install UniFi Protect MCP
Platform CLI
claude mcp add --env UNIFI_HOST=<UNIFI_HOST> --env UNIFI_USERNAME=<UNIFI_USERNAME> --env UNIFI_PASSWORD=<UNIFI_PASSWORD> --env UNIFI_API_KEY=<UNIFI_API_KEY> --env UNIFI_PORT=<UNIFI_PORT> --transport stdio protect -- uvx unifi-protect-mcpReplace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from unifi-protect-mcp <command>
Platform CLI
codex mcp add protect --env UNIFI_HOST=<UNIFI_HOST> --env UNIFI_USERNAME=<UNIFI_USERNAME> --env UNIFI_PASSWORD=<UNIFI_PASSWORD> --env UNIFI_API_KEY=<UNIFI_API_KEY> --env UNIFI_PORT=<UNIFI_PORT> -- uvx unifi-protect-mcpReplace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from unifi-protect-mcp <command>
Config file
{
"mcpServers": {
"protect": {
"command": "uvx",
"args": [
"unifi-protect-mcp"
],
"env": {
"UNIFI_HOST": "<UNIFI_HOST>",
"UNIFI_USERNAME": "<UNIFI_USERNAME>",
"UNIFI_PASSWORD": "<UNIFI_PASSWORD>",
"UNIFI_API_KEY": "<UNIFI_API_KEY>",
"UNIFI_PORT": "<UNIFI_PORT>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from unifi-protect-mcp <command>
Config file
{
"servers": {
"protect": {
"type": "stdio",
"command": "uvx",
"args": [
"unifi-protect-mcp"
],
"env": {
"UNIFI_HOST": "<UNIFI_HOST>",
"UNIFI_USERNAME": "<UNIFI_USERNAME>",
"UNIFI_PASSWORD": "<UNIFI_PASSWORD>",
"UNIFI_API_KEY": "<UNIFI_API_KEY>",
"UNIFI_PORT": "<UNIFI_PORT>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from unifi-protect-mcp <command>
Platform CLI
gemini mcp add -e UNIFI_HOST=<UNIFI_HOST> -e UNIFI_USERNAME=<UNIFI_USERNAME> -e UNIFI_PASSWORD=<UNIFI_PASSWORD> -e UNIFI_API_KEY=<UNIFI_API_KEY> -e UNIFI_PORT=<UNIFI_PORT> protect uvx unifi-protect-mcpReplace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from unifi-protect-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about UniFi Protect MCP
How do I install UniFi Protect MCP in Claude Code?
Register the marketplace using /plugin marketplace add sirkirby/unifi-mcp, then install the package with /plugin install unifi-protect@unifi-plugins. Run /unifi-protect:unifi-protect-setup to configure your controller connection and store credentials in the system keychain.
What does UniFi Protect MCP do?
It lets MCP-compatible agents inspect UniFi Protect video feeds, smart alerts, sensors, and alarm logs. You can query surveillance events and adjust hardware settings with natural language prompts.
Why is UNIFI_PROTECT_API_KEY required?
Controller Integration API endpoints require this key to modify microphone volume, HDR mode, and floodlight settings. Standard log retrieval and event searches only require regular local administrator credentials.
