UniFi Protect 安防监控MCP服务

UniFi Protect MCP Server

An MCP (Model Context Protocol) server that exposes UniFi Protect's Integration REST API as tools for Claude Code and other MCP clients. Aligned with UniFi Protect API 7.3.70, with tools covering cameras, lights, sensors, chimes, viewers, sirens, fobs, relays, speakers, bridges, link stations, alarm hubs, arm profiles, live views, files, users, point-of-sale events, NVR status, and WebSocket subscriptions.

Prerequisites

• Node.js 22.x (22.19 or newer) or 24.x — see engines in package.json
• A UniFi Protect system with the Integration API enabled
• An API key generated from your UniFi Protect console (see Choosing an API key)

Setup

Quick start (npx)

Add to Claude Code with a single command — no clone or build needed:

claude mcp add-json unifi-protect '{"command":"npx","args":["-y","@owine/unifi-protect-mcp@latest"],"env":{"UNIFI_PROTECT_HOST":"192.168.1.1","UNIFI_PROTECT_API_KEY":"your-api-key"}}' -s user

Use -s user for global availability across all projects, or -s project for the current project only.

A local console usually has a self-signed certificate, so the first call fails with a certificate error until you trust it: see Self-signed console certificates.

@latest runs the newest release every time the server starts, including a new major version. To take fixes but choose when to make breaking upgrades, pin the major version you have tested instead (@owine/unifi-protect-mcp@<major>).

From source

If you prefer to build locally:

git clone https://github.com/owine/unifi-protect-mcp.git
cd unifi-protect-mcp
corepack enable   # provides pnpm at the version pinned in package.json
pnpm install
pnpm run build

This project uses pnpm — npm install ignores pnpm-lock.yaml and may resolve different dependency versions than CI.

Then add to Claude Code:

claude mcp add-json unifi-protect '{"command":"node","args":["/path/to/unifi-protect-mcp/dist/index.js"],"env":{"UNIFI_PROTECT_HOST":"192.168.1.1","UNIFI_PROTECT_API_KEY":"your-api-key"}}' -s user

Environment Variables

The startup line in the MCP host's server log says whether the server is read-only or read-write. A configuration error names the variable at fault, and the server exits.

Self-signed console certificates

UniFi consoles ship with a self-signed certificate, so the first call to a local console usually fails with a certificate error. The safe fix is to trust that one certificate. Save it:

openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null | openssl x509 > ~/.config/unifi-protect-console.pem

Set UNIFI_PROTECT_CA_CERT to the file's absolute path (for example /home/you/.config/unifi-protect-console.pem); MCP hosts do not expand ~ or $HOME in env. The server then accepts exactly that certificate, even though it is issued to a name like unifi.local and you connect by IP. This also works for a certificate issued by a CA (one you installed on the console yourself): pinning the console's own certificate is enough, without the CA's. Any other certificate must chain to the file and match the hostname. If the network between you and the console is not trusted, compare the fingerprint (openssl x509 -in <file> -noout -fingerprint -sha256) with the console's. If the console later generates a new certificate, save it again.

Setting UNIFI_PROTECT_VERIFY_SSL=false instead turns certificate checks off for this server's connections to the console, and only those (other TLS connections in the process are unaffected). Anyone who can intercept that traffic can then read the API key, so use it only on a network you trust.

Choosing an API key

• Use the least-privileged key that works. Create the key from an admin account with no more access than you need. For the default read-only mode, that means an admin with view-only access to Protect; use a full-access admin only with UNIFI_PROTECT_READ_ONLY=false.
• Prefer a local console key to a Site Manager key. A Site Manager key (Cloud Connector, api.ui.com) reaches every console on the account and travels over the internet.

Manual Configuration

Alternatively, add to your ~/.claude.json under the top-level "mcpServers" key, or to Claude Desktop's claude_desktop_config.json the same way:

{
  "mcpServers": {
    "unifi-protect": {
      "command": "npx",
      "args": ["-y", "@owine/unifi-protect-mcp@latest"],
      "env": {
        "UNIFI_PROTECT_HOST": "192.168.1.1",
        "UNIFI_PROTECT_API_KEY": "your-api-key",
        "UNIFI_PROTECT_CA_CERT": "/absolute/path/to/console.pem"
      }
    }
  }
}

Cloud Connector

To reach a console through Ubiquiti's Cloud Connector instead of over the local network, set UNIFI_PROTECT_HOST=api.ui.com and UNIFI_PROTECT_CONSOLE_ID to the console's ID, and supply a Site Manager API key (unifi.ui.com → Settings → API) as UNIFI_PROTECT_API_KEY. That is a different credential from a local console API key. Requests are routed through /v1/connector/consoles/{id}.

TLS verification stays on: the server refuses to start with UNIFI_PROTECT_VERIFY_SSL=false or UNIFI_PROTECT_CA_CERT for api.ui.com. Ubiquiti's cloud has a publicly trusted certificate, and a pinned certificate would replace the public certificate authorities for this server's connections.

Find your console ID with:

curl -s https://api.ui.com/v1/hosts -H "X-API-KEY: $KEY" | jq -r '.data[].id'

WebSocket subscriptions do not work over Cloud Connector. The connector proxies REST calls but returns HTTP 404 on a WebSocket upgrade, so protect_subscribe_devices and protect_subscribe_events fail fast with an explanatory error. Every other tool, including snapshots and file uploads, works. Connect directly to the console host if you need subscriptions.

Note that /v1/hosts reports protect under controllers for consoles where Protect is merely available, not necessarily installed; only consoles actually running Protect will answer.

Setting UNIFI_PROTECT_CONSOLE_ID against a local host is not fatal: the server logs a warning and talks to that host directly.

Upgrading to 3.0

3.0 puts more actions behind confirmation: physical outputs, disarming, anything that weakens alarm coverage, and live video and two-way audio. It also scopes TLS settings to this server, keeps every result within what one MCP message can carry, and makes cancellation stop the request to Protect.

If you use the server only through an LLM client (Claude Code, Claude Desktop, …), the model reads the new parameters from the tool schemas, so most setups need no change. Check three things:

• Cloud Connector with verification off no longer starts. Unset UNIFI_PROTECT_VERIFY_SSL when UNIFI_PROTECT_HOST=api.ui.com.
• Spellings of UNIFI_PROTECT_READ_ONLY / UNIFI_PROTECT_VERIFY_SSL that 2.x ignored now take effect (table below).
• Expect more approval prompts. Update tools and every confirm-gated tool are now annotated destructive (below).

Read on if you call tools from scripts or saved agent configurations, or keep allow-lists keyed on tool annotations.

Check your environment variables first

2.x treated only the exact string false as false. 3.0 also accepts 0, no and off, in any case, so a value that 2.x silently ignored now takes effect:

Any other unrecognized value keeps the safe default (read-only, verification on), as before. New: UNIFI_PROTECT_CA_CERT verifies a console's self-signed certificate (see Self-signed console certificates). Configuration errors now name the variable at fault, and the startup log line says whether the server is read-only or read-write.

Tool input changes (breaking)

A call that leaves out state or enable, or passes a malformed ID, fails input validation. A call without confirm: true returns an error result ("This action requires confirmation: …"), so the agent can ask you and call again.

Toggling was removed because it is not safe to retry: a repeated toggle flips a gate or lock back to where it started. To act on the current state, read it first: each entry in outputs from protect_get_relay carries a state, and protect_get_alarm_hub reports alarmHub.output keyed by channel.

// 2.x: toggles output 0
{ "id": "<relay id>", "outputId": 0 }
// 3.0: explicit, so a repeat leaves the output as asked (a pulseDuration pulses again)
{ "id": "<relay id>", "outputId": 0, "state": "on", "confirm": true }

Relaxed: a dryRun: true preview never needs confirm. In 2.x, protect_disable_mic and protect_trigger_alarm_webhook rejected a dry run without confirm: true. Calls that send both still work.

New: every list tool except protect_list_nvrs takes optional limit and offset. A call with neither returns the whole list, as before.

Annotation changes (breaking for allow-lists)

• protect_update_camera, every protect_update_<device> tool, protect_update_arm_profile and protect_update_liveview are now destructiveHint: true, and so is every tool that takes confirm (protect_stop_siren, protect_set_current_arm_profile, protect_create_rtsp_stream, protect_create_talkback, protect_disable_arm_alarm, protect_activate_relay_output, protect_trigger_alarm_hub_output among them). MCP clients that auto-approve non-destructive tools will now ask before running them, and allow-lists keyed on the annotation need updating.
• Every tool now has a title and openWorldHint: false.

Stricter validation

• UNIFI_PROTECT_HOST is parsed as a URL authority. A pasted https://192.168.1.1/ now works, and :443 is dropped. A path, credentials, a non-numeric or out-of-range port, or an unbracketed IPv6 address now fails at startup instead of at the first request. Write IPv6 as [2001:db8::1] or [2001:db8::1]:7443.
• protect_upload_file rejects base64Data that is not valid base64 (bad characters, length or padding), and empty input, where 2.x uploaded corrupt bytes without an error. A data: URL prefix and line breaks are accepted. A file too large to fit one MCP message is refused with "File too large to send in one MCP message"; in 2.x an oversized request closed the server's stdio transport and the server exited with nothing logged.
• protect_update_liveview rejects a body whose settings.id differs from id.

Output changes

• Text results are compact JSON, not indented. structuredContent is unchanged; use it if you parse results.
• Single-object results and dry-run previews now pass MCP clients' output validation. In 2.x, a top-level field the schema did not list, or any dry-run preview of a tool with an output schema, failed with -32602.
• A snapshot, response or other result too large for one MCP message is refused with an error saying so. In 2.x it was sent, and the MCP client dropped the connection.
• The protect_upload_file dry-run preview reports byteLength (decoded size) in place of dataLength (base64 string length).
• protect_subscribe_devices / protect_subscribe_events stop at a message cap or a size budget, whichever comes first (both stated in each tool's description), and add truncated: true. duration is the time actually spent listening. A listen that fails before any message arrives (refused or unauthorized socket) returns an error result; in 2.x it returned {messages: [], error} as a success. One that fails partway still returns what it collected, with error.
• A timeout names the call and what to do: PATCH /cameras/…: Protect did not respond within … s, followed by "Retry when the console responds" for reads, or "The change may still have been applied; check before retrying" for writes. Snapshots and uploads time out before the MCP client's own request timeout, so you see this message instead of a bare client timeout.
• Network and TLS errors name the underlying cause, e.g. fetch failed: connect ECONNREFUSED …, instead of a bare fetch failed.
• A subscription that the console refuses, closes or drops before any message arrives returns an error naming why, instead of an empty list that reads as a quiet site. So does one whose window ends before the connection is established, or whose first message is too large to return.
• A list tool reads a response of up to several times one MCP message and returns the page asked for, so limit and offset work on a site whose full list would not fit.
• Cancelling a tool call aborts its request to Protect, and a cancelled subscription closes its socket. In 2.x a cancelled relay switch could still land afterwards.
• The server reports its real package version to MCP clients; 2.x always reported 1.0.0. It also sends server instructions (see Safety Features).

For packagers

undici is a new runtime dependency (scoped TLS and connection keep-alive). Requests go through undici's own fetch rather than Node's, so:

• They speak HTTP/1.1, as before, and send User-Agent: unifi-protect-mcp/<version>.
• An HTTP proxy is used as Node's built-in fetch would: from HTTPS_PROXY / HTTP_PROXY, minus NO_PROXY, only when NODE_USE_ENV_PROXY=1 or --use-env-proxy is set. A dispatcher installed with undici's setGlobalDispatcher no longer applies. The subscription WebSocket never used a proxy, and still does not.

Safety Features

• Tool annotations. Every tool declares readOnlyHint, destructiveHint and openWorldHint: false (each talks only to your console), plus a readable title, so MCP clients such as Claude Code can decide when to ask you. destructiveHint: true marks every tool that deletes or replaces existing state, which includes every protect_update_* tool, and every tool that takes confirm. Clients that auto-approve non-destructive tools ask before those. The tool tables below mark them DESTRUCTIVE.
• Server instructions. On connect, the server gives the MCP host a short guide for the model, matched to read-only or read-write mode. It says to treat names and event text from the console as data, not instructions; that RTSPS and talkback URLs are credentials; and, when writes are enabled, to preview with dryRun and ask you before passing confirm.
• Read-only mode. On by default. Only the read tools (list, get, snapshot, subscriptions) are registered; write tools do not exist for the model, and registering one in read-only mode fails at startup. Set UNIFI_PROTECT_READ_ONLY=false to enable writes. Read-only mode still returns RTSPS URLs from protect_get_rtsp_streams, and those are credentials for live video.
• Confirmation parameter. Tools that are irreversible, switch physical outputs, trigger the alarm webhook, stop a siren, disarm or weaken alarm coverage, or open live video or two-way audio refuse to act unless the call carries confirm: true. Without it the tool returns an error naming the action, so the agent can ask you first. protect_update_sensor, protect_update_fob, protect_update_siren and protect_update_arm_profile need it only when the change touches alarm-related settings (each tool's description names them); renames and LED changes do not. confirm is filled in by the model, so it is a prompt for the model to ask you, not a lock; for a human gate, keep your MCP client's approval prompts on for destructive tools.
• Dry-run support. Every write tool accepts dryRun: true and returns the request it would send (dryRun, action, path, body) without changing anything. A dry run never needs confirm.
• Request safety. IDs must be IDs returned by list and get tools, and a request path that would resolve outside the Integration API is refused before it is sent. Redirects are refused, so the API key is never forwarded. Cancelling a tool call aborts its request to Protect.

See SECURITY.md for reporting vulnerabilities and operating the server safely.

Structured output

Read tools, and write tools that return the resource, declare an outputSchema, and return structuredContent alongside compact JSON text. Schemas are published as loose objects, so a field a firmware update adds flows through instead of failing validation. A list's items are under result; a paged list also has totalCount and offset. protect_get_snapshot returns an image. A dry run returns {dryRun, action, path, body}. Action endpoints that return no body succeed with an empty result.

Tools

DESTRUCTIVE marks tools annotated destructiveHint: true. Requires confirm: true marks tools that take confirm; every one of them is also DESTRUCTIVE. Pages with limit/offset marks list tools that take them.

System

Subscriptions

Cameras

Lights

Sensors

Chimes

Viewers

Sirens

Fobs

Relays

Speakers

Bridges

Link Stations

Alarm Hubs

Arm Profiles — local alarm manager

Live Views

Alarm & Files

Users

Point of Sale

Troubleshooting

Configuration errors go to the MCP host's server log and the server exits. Tool errors reach the agent as results starting with Error:.

Development

The Node version used for development is pinned in .nvmrc. With fnm installed, fnm use reads it automatically on cd.

pnpm run build         # Compile TypeScript
pnpm start             # Run the server
pnpm run typecheck     # Type-check src/ and tests/ without emitting
pnpm run lint          # ESLint, type-aware
pnpm run lint:fix      # ESLint with auto-fix
pnpm test              # Run all tests (vitest)
pnpm run test:watch    # Run tests in watch mode
pnpm run test:coverage # Run tests with coverage
pnpm run test:package  # Pack, install the tarball and smoke-test it over stdio

Git hooks are managed by lefthook — pnpm exec lefthook install enables them. Pre-commit runs ESLint on staged files, a full typecheck, and a GitGuardian secret scan when ggshield is installed (skipped otherwise), so fnm and pnpm both need to be on your PATH.

Commit conventions

This project uses conventional commits in pull request titles and release-drafter for releases. Pull requests are squash-merged, so the title is the commit subject:

• feat: ... — new feature (minor version bump)
• fix: ... — bug fix (patch version bump)
• deps: ... — dependency update (patch version bump; Renovate's type for package bumps)
• feat!: ... — breaking change (major version bump); the ! must be in the title, a BREAKING CHANGE: footer is not read
• chore:, docs:, ci:, etc. — no version bump

Every push to main updates a draft GitHub Release with the next version and its notes. A maintainer publishes the draft, which builds, tests and publishes that tagged commit to npm with provenance. To release a different version, edit the draft's tag and title before publishing. Release notes after 3.0.0 are in GitHub Releases; CHANGELOG.md covers 3.0.0 and earlier.

License

MIT