UniFi Protect MCP

UniFi Protect MCP Server

AI アシスタントやその他の MCP 対応クライアント向けに、UniFi Protect のツールを提供する MCP サーバーです。カメラ、イベント、スマート検知、「あらゆるものを検索」検知検索、録画、ライト、センサー、チャイム、既知の顔、ナンバープレート、Alarm Manager を、安全な権限設定をデフォルトとし、すべての変更操作で実行前にプレビューと確認を行いながら照会できます。

自動化サービスや MCP アダプターなど、HTTP 経由で統合するソフトウェアでは、REST および GraphQL による読み取り、アクション、SSE イベントに unifi-api-server を使用してください。

インストール

Claude Code（推奨）

このプラグインは、MCP サーバー、ツール検出用のエージェントスキル、ガイド付きセットアップコマンドをインストールします。

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

次に、対話型セットアップを実行して、コントローラーへの接続を設定します。

/unifi-protect:unifi-protect-setup

画面の案内に沿って、コントローラーのホスト、認証情報、権限の設定を入力します。認証情報はファイルまたはコマンドプロバイダーとして指定し、チャットには入力しません。セットアップ結果はプラグインの Claude Code オプションとして保存され、すべてのプロジェクトに適用されます。オプションとして入力したパスワードまたは API キーは、システムのキーチェーンに保存されます。接続するには、セットアップ後に Claude Code の新しいセッションを開始してください。

プロジェクトの .claude/settings.local.json に設定を保存していた 1.0.0 より前のプラグインバージョンからアップグレードしますか？プラグインのアップグレードガイドに従ってください。

Codex

マーケットプレイスを登録し、Codex の /plugins UI から unifi-protect をインストールします。

codex plugin marketplace add sirkirby/unifi-mcp

インストール後、Codex に UniFi Protect のセットアップスキルを使うよう依頼してください。セットアップでは、コントローラーの設定を含むバージョン固定の MCP サーバーエントリが Codex の config.toml に保存され、Codex の再起動を促すメッセージが表示されます。プラグインをアップグレードするたびに、--refresh を付けてセットアップを再実行してください。

PyPI / Docker

# PyPI
uvx unifi-protect-mcp@latest
# 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

使用例

接続したら、自然な言葉で AI エージェントに尋ねるだけです。

「過去 1 時間にモーションを検知したカメラをすべて一覧表示して」

「今日、玄関のカメラで発生したスマート検知イベントを表示して。人物と車両だけでいいです」

「今週、白いバンが車道で検知された記録を検索して」

「今週、モーションイベントが最も多かったカメラはどれですか？何か異常な傾向はありますか？」

「オフライン、または接続が不安定なカメラはありますか？」

「昨夜の午前 2 時から午前 5 時の間に、車道のカメラで記録されたイベントをすべて表示して」

「今日、警告を発したセンサーと、その測定値をすべて表示して」

カメラとイベントの照会は、すべてデフォルトで読み取り専用です。変更操作（カメラ設定、ライトの操作）では、プレビューしてから確認するフローを使用します。

設定

サーバーのプロセス環境にこれらの変数を設定してください。プラグインのセットアップスキルでは Codex と OpenClaw 向けにすでに設定されています。Claude Code では、プラグインがそのオプションをこれらの変数に割り当てます。サーバーは .env や作業ディレクトリ内の YAML ファイルを自動的に読み込みません。信頼できる env ファイルをランチャーで明示的に読み込むか（Docker の env_file: はサポートされています）、絶対パスの CONFIG_PATH でカスタム YAML を指定してください。移行例については設定を参照してください。

コントローラーホストが設定されていない場合でも、サーバーはセットアップモードで起動します。クライアントに設定方法を通知し、読み取り専用の protect_setup_status ツールのみを提供し、コントローラーへの接続は行いません。

# 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=             # Required for camera HDR/mic volume and light power/brightness/PIR settings
# UNIFI_PROTECT_PORT=443             # Controller HTTPS port
# UNIFI_PROTECT_VERIFY_SSL=false     # SSL certificate verification

カメラの HDR とマイク音量に加えて、フラッドライトの出力、明るさ、PIR 感度、点灯時間は、uiprotect 16.x の Protect 公開 Integration API を使用するようになりました。これらの設定を使用する前に、UNIFI_PROTECT_API_KEY（または共有フォールバックの UNIFI_API_KEY）を設定し、サーバーを再起動してください。その他の Protect 操作には引き続きセッション認証情報が必要です。キーがない場合や、公開デバイス ID に互換性がない場合は、リクエスト内の設定が書き込まれる前に失敗します。

マイク音量の更新では 1～100 を指定できます。0 は公開 API によって拒否されます。既存の HDR エイリアスは保持されます。true／on／normal は auto を意味し、false は off を意味します。また、always／superHdr は公開 HDR の on を指定します。ライトの明るさは引き続き 1～6、感度は 0～100、点灯時間は 15～900 秒です。light_on と is_light_on は同等の入力で、強制点灯を制御します。強制点灯をオフにしても、動体検知による点灯は無効になりません。

設定の更新では、プレビュー／確認とポリシーによる制限が引き続き適用されます。書き込み前にリクエストが検証されますが、コントローラーでエラーが発生した場合、更新が一部だけ適用されることがあります。更新に失敗すると、適用された設定を含むエラーが返されるため、呼び出し元は再試行する前に現在の状態を確認できます。

フォールバック： 共有の UNIFI_* 変数（例：UNIFI_HOST）も使用できます。サーバーはまず UNIFI_PROTECT_* を確認し、サーバー固有の変数が設定されていない場合は UNIFI_* にフォールバックします。コントローラーが 1 台の構成では、共有変数だけで十分です。

MCP の応答サイズ

構造化出力をすでに提供しているツールの結果では、adaptive がデフォルトの応答モードです。各リクエストは、クライアントの製品名やアプリケーションのバージョンではなく、MCP の初期化時に通知された日付ベースの正規の protocolVersion に基づいて分類されます。MCP 2025-06-18 以降を通知するリクエストには、簡潔な content と完全な結果を一度だけ structuredContent で返します。それ以前のリビジョン（2024-11-05 や 2025-03-26 など）を通知するリクエスト、またはリビジョンのメタデータが欠落しているか不正な形式のリクエストには、互換性を保つ完全な JSON を content で返します。UNIFI_PROTECT_MCP_CONTENT_MODE を compat に設定すると重複する互換形式を強制でき、compact に設定すると、ネゴシエーション済みのリクエスト以外で簡潔なテキストと完全な構造化出力を強制できます。このサーバー固有の変数は UNIFI_MCP_CONTENT_MODE より優先されます。通知されたリビジョンにかかわらず、content からのみ完全な結果を取得するクライアントには compat を使用してください。

遅延読み込みのメタツール（*_tool_index、*_execute、*_batch、*_batch_status、および遅延読み込み専用の *_load_tools）は、引き続き content のみを返します。これらは、上記の 2025-06-18 より前のプロトコルカテゴリには該当しません。構造化された内部結果の場合、*_execute と *_batch_status は、入れ子になったトランスポートのペアではなく、正規化された単一の JSON ペイロードを content で公開します。content のみの実行結果は変更されません。応答モードを使って、これらのメタツールを structuredContent 対応にすることはできません。

Protect と併せて Network を有効にしている場合、最大サイズのソース応答はそれぞれ個別に制限されます。unifi_get_dashboard はデフォルトで summary=true になり、unifi_list_rogue_aps はデフォルトで最大 100 件のレコードを含む要約ページを返します。summary=false にすると、選択したデータ全体が返されます。

AI を活用したアラームには SuperAdmin が必要です。 アラームルールツール（protect_alarm_list_rules ／ protect_alarm_get_rule ／ protect_alarm_create_rule ／ protect_alarm_update_rule ／ protect_alarm_delete_rule）は、アカウントが SuperAdmin の場合、最新の UniFi-OS Alarm Manager を透過的に使用し、それ以外の場合は従来のオートメーション表示にフォールバックします。最新の経路では AI を活用したアラーム（例：AI Natural Language）が表示・管理されますが、従来の経路ではこれらのルールを確認できず、表示範囲が限定されている場合は標準の MCP _meta 通知が応答に含まれます。AI アラームを表示・管理するには、Protect をホストしているコンソールでアカウントに SuperAdmin を付与してください。影響範囲：スタンドアロンの UNVR では Protect のみに限定されます。Network と UniFi-OS を統合した UDM コンソールでは、SuperAdmin により Network ／ UniFi-OS の制御権限も付与されます。

機密性の高い応答フィールド

Protect ツールは、MCP クライアントにデータを返す前に、シークレットを含むストリームフィールドをデフォルトでマスキングします。これには protect_get_camera_streams の RTSP ／ RTSPS ストリームエイリアスと URL が含まれます。生のストリーム値が必要な場合は、信頼できるローカル管理プロセスで UNIFI_PROTECT_REDACT_SENSITIVE_FIELDS=false、またはグローバルポリシーフラグ UNIFI_REDACT_SENSITIVE_FIELDS=false を設定してマスキングを無効にしてください。

実行

# 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

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"
      }
    }
  }
}

機能

• カメラ -- 一覧表示、詳細確認、スナップショット、RTSP ストリーム、PTZ 制御、設定、録画の切り替え、再起動
• イベント -- 過去のイベント、スマート検知（人物／車両／動物／荷物）、Find Anything 検知検索、サムネイルの照会
• リアルタイムストリーミング -- MCP リソースのサブスクリプションとポーリングに対応した WebSocket イベントバッファー
• 録画 -- ステータス、利用可能状況、タイムラプスに対応したクリップのエクスポート
• 既知の顔 -- 顔認識グループの一覧表示、名前の変更、統合、削除
• デバイス -- ライト（明るさ、PIR 感度）、センサー（温度、湿度、動き）、チャイム（音量、トリガー）
• ライブビュー -- 複数カメラのレイアウトの一覧表示と詳細確認
• システム -- NVR 情報、ヘルスメトリクス、ファームウェアのステータス、接続中のビューアー

エージェントスキル

Protect プラグインには、MCP ツールと連携するエージェントスキルが 1 つ付属しています。

セキュリティダイジェスト

接続されているすべての UniFi システムを対象に、製品を横断してイベントを分析し、簡潔なセキュリティ概要を生成します。

• ソース： Protect のカメライベント、Access のドアイベント、Network のファイアウォールアクティビティ
• 重大度の分類： 時間帯の状況（営業時間内、営業時間外、深夜）とイベントの種類（人物検知、車両、ドアアクセス、ファイアウォールによるブロックなど）に基づいてイベントを分類します
• 製品横断の相関分析： 製品をまたぐパターンを検出する、組み込みの相関ルールが 5 つあります：
  • ドアカメラで動きを検知したが、対応するバッジでの入館記録がない
  • 短時間に複数回のドアアクセス失敗
  • 同じ時間帯に、人物検知とファイアウォールによるブロックが発生
  • 営業時間外のカメラアクティビティに、Access のイベントが伴わない
  • 敷地周辺で車両を繰り返し検知
• アクティビティ件数： すべてのソースの合計を集計し、状況をひと目で把握できます

プラグインのインストール後、スキルコマンドから呼び出します：

/unifi-protect:security-digest

イベントの改善

イベントレスポンスの camera_name

すべてのイベント関連ツールで、各イベントオブジェクトに camera_id とともに camera_name が含まれるようになりました。名前は起動時にキャッシュされたブートストラップデータから解決されるため、追加の API 呼び出しは不要です。

対象ツール：protect_list_events、protect_list_smart_detections、protect_recent_events

変更前：

{ "camera_id": "abc123", "type": "motion", ... }

変更後：

{ "camera_id": "abc123", "camera_name": "Front Door", "type": "motion", ... }

これにより、ID と名前を対応付けるためだけに、別途 protect_list_cameras を呼び出す必要がなくなります。

コンパクトモード

protect_list_events と protect_list_smart_detections では、レスポンスから情報量の少ないフィールド（thumbnail_id、category、sub_category、is_favorite）を除外する compact=true パラメーターを指定できます。これにより、レスポンスのサイズを約 40% 削減できます。

# Standard call
protect_list_events(limit=50)

# Compact — recommended for digests, summaries, and context-constrained workflows
protect_list_events(limit=50, compact=True)

概要の作成時や、トークン予算が重要となる後続のプロンプトにイベントを渡す際は、コンパクトモードをデフォルトとして使用することを推奨します。

ドキュメント

• 設定 -- 環境変数の完全なリファレンス、YAML 設定、Protect 固有のオプション
• 権限 -- 権限システム、カテゴリのデフォルト設定、変更操作を有効にする方法
• ツールカタログ -- カテゴリ別に整理された 63 個すべてのツール
• イベントストリーミング -- リアルタイムイベントのアーキテクチャ、MCP リソース、ポーリング
• トラブルシューティングとサポートバンドル -- 確認済みのサポート情報、接続の問題、SSL、ツールが見つからない場合

開発

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

モノレポのワークフロー全体については、ルートの CONTRIBUTING.md を参照してください。

ライセンス

MIT