UniFi Access MCP

UniFi Access MCP サーバー

AI アシスタントや、その他の MCP 対応クライアント向けに UniFi Access のツールを公開する MCP サーバーです。ドア、認証情報、アクセスルール、訪問者、イベント、デバイスを管理できます。デフォルトでは安全な権限設定を採用し、すべての変更操作で実行前にプレビューして確認できます。

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

インストール

Claude Code（推奨）

プラグインをインストールすると、MCP サーバー、ツール検出用のエージェントスキル、ガイド付きセットアップコマンドが導入されます。

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

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

/unifi-access:unifi-access-setup

このセットアップでは、Access コントローラーへの接続手順を案内し、デュアル認証システム（読み取りには API キー、変更操作にはユーザー名とパスワードを使用）について説明したうえで、権限を設定します。認証情報はファイルまたはコマンドプロバイダーから渡すため、チャットに入力する必要はありません。セットアップ結果はプラグインの Claude Code オプションとして保存され、すべてのプロジェクトで適用されます。オプションとして入力したパスワードや API キーは、システムのキーチェーンに保存されます。接続するには、セットアップ後に新しい Claude Code セッションを開始してください。

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

Codex

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

codex plugin marketplace add sirkirby/unifi-mcp

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

PyPI / Docker

# PyPI
uvx unifi-access-mcp@latest
# or: pip install unifi-access-mcp

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

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

使用例

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

「今日、オフィスでバッジを使って入室したのは誰ですか？ドアアクセスイベントをすべて時系列で表示してください」

「今後 30 日以内に有効期限が切れるアクセス認証情報をすべて一覧表示してください」

「今週、サーバールームで失敗したバッジ認証を表示してください。何か傾向はありますか？」

「今日、アクセスイベントが最も多かったドアはどれですか？」

「明日の午前 9 時から午後 5 時まで正面玄関にアクセスできる、John Smith の訪問者パスを作成してください」

「ドアのポリシーを監査してください。営業時間外のアクセスを許可しているドアはどれですか？」

すべてのクエリはデフォルトで読み取り専用です。変更操作（訪問者パス、認証情報の変更、ドアの制御）には、プレビューしてから確認するフローを使用します。

設定

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

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

# Server-specific variables (recommended)
UNIFI_ACCESS_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_ACCESS_USERNAME=admin         # Local admin username
UNIFI_ACCESS_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_ACCESS_API_KEY=             # Official UniFi API key (dual auth)
# UNIFI_ACCESS_PORT=443             # Controller HTTPS port
# UNIFI_ACCESS_VERIFY_SSL=false     # SSL certificate verification

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

MCP のレスポンスサイズ

構造化出力をすでに提供するツール結果では、adaptive がデフォルトのレスポンスモードです。各リクエストは、MCP 初期化時に通知された日付ベースの正規の protocolVersion に基づいて分類されます。クライアントの製品名やアプリケーションのバージョンには基づきません。MCP 2025-06-18 以降を通知するリクエストでは、簡潔な content と、完全な結果を一度だけ含む structuredContent が返されます。それ以前のリビジョン（2024-11-05 や 2025-03-26 など）を通知するリクエスト、またはリビジョンのメタデータが欠落しているか不正なリクエストでは、互換性を保つ完全な JSON が content に含まれます。互換性のための重複形式を強制するには UNIFI_ACCESS_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 ペイロードを 1 つ content に公開します。content のみの実行結果は変更されません。レスポンスモードによって、これらのメタツールが structuredContent に変わることはありません。

Network が Access と同時に有効になっている場合、最大サイズのソースレスポンスにはそれぞれ独立した上限が適用されます。unifi_get_dashboard はデフォルトで summary=true となり、unifi_list_rogue_aps はデフォルトで最大 100 件のレコードを含む要約ページを返します。summary=false にすると、選択したデータ全体が返されます。

2 種類の認証方式

Access サーバーは、独立した 2 つの認証経路をサポートしています。

1. API キー -- 専用の Access API ポート（デフォルトは 12445）で py-unifi-access を使用します。読み取り専用のクエリやデバイスの一覧表示に最適です。
2. ローカルプロキシセッション -- UniFi OS Console（ポート 443）の /api/auth/login 経由でログインし、/proxy/access/api/v2/... 経由でリクエストをプロキシします。ドアの施錠・解錠、認証情報の管理、ポリシー、訪問者、イベントに必要です。

少なくとも 1 つの経路を設定する必要があります。両方を利用できる場合、各ツールは最適な経路を選択します。変更を伴うツールの多くでは、ローカルプロキシセッションが必要です。

シークレットの秘匿

Access ツールは、MCP クライアントにデータを返す前に、デフォルトで認証情報のシークレットを秘匿します。読み取り、一覧表示、作成プレビューでは、認証情報の token と pin_code の値は ***REDACTED*** として表示されます。信頼できるローカル管理プロセスで秘匿を無効にし、元の値が必要な場合は、UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false またはグローバルポリシーフラグ UNIFI_REDACT_SENSITIVE_FIELDS=false を設定してください。更新時に既存のシークレットを保持するには、***REDACTED*** マーカーを渡さず、該当フィールドを省略してください（マーカーを渡すと拒否されます）。

実行

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

# Docker
docker run -i --rm \
  -e UNIFI_ACCESS_HOST=192.168.1.1 \
  -e UNIFI_ACCESS_USERNAME=admin \
  -e UNIFI_ACCESS_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-access-mcp:latest

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "unifi-access": {
      "command": "uvx",
      "args": ["unifi-access-mcp"],
      "env": {
        "UNIFI_ACCESS_HOST": "192.168.1.1",
        "UNIFI_ACCESS_USERNAME": "admin",
        "UNIFI_ACCESS_PASSWORD": "your-password"
      }
    }
  }
}

機能

• ドア -- ドアの一覧表示、詳細確認、施錠・解錠、ドアグループ、リアルタイムのステータス
• ポリシー -- アクセスポリシーとスケジュールの一覧表示、詳細確認、更新
• 認証情報 -- NFC カード、PIN、モバイル認証情報の一覧表示、詳細確認、作成、失効
• 訪問者 -- 時間制限付きアクセスが可能な訪問者用パスの一覧表示、詳細確認、作成、削除
• イベント -- 過去のイベントの検索、リアルタイムの WebSocket バッファー、アクティビティの要約
• デバイス -- アクセスハブ、リーダー、リレー、インターコムの一覧表示、詳細確認、再起動
• システム -- コントローラー情報、ヘルスメトリクス、ユーザー一覧表示

エージェントスキル

Claude Code プラグインには、AI アシスタントが Access を効果的に利用する方法を学ぶためのエージェントスキルが含まれています。

• UniFi Access — ドア制御、認証情報、訪問者、アクセス ポリシー、イベント監視のためのコアスキルです。二重認証システム、WebSocket バッファーによるリアルタイムイベントストリーミング、物理ドア操作のプレビューと確認のフローに関するガイダンスが含まれています。
• Setup — コントローラーへの接続、認証情報の設定、権限の設定を順に案内する対話型の構成ウィザードです。

スキルはプラグインのインストール時に自動的に利用可能になります。

クロスプロダクトスキル

Access プラグインを Protect プラグインと併せてインストールすると、security-digest スキルの分析にドアイベントを含めることができます。バッジによる入室、アクセス拒否イベント、時間外アクセスを Protect のカメラの動きやアラートと関連付けることで、UniFi 環境全体を対象とした、より充実したセキュリティ概要を作成します。

追加の設定は不要です。両方のプラグインが有効であれば、スキルは両方のサーバーから自動的に情報を取得します。

ドキュメント

• 構成 -- 環境変数の全リファレンス、YAML 構成、Access 固有のオプション
• 権限 -- 権限システム、カテゴリごとの既定値、変更を有効にする方法
• ツールカタログ -- カテゴリ別に整理された全 37 個のツール
• イベントストリーミング -- リアルタイムイベントのアーキテクチャ、WebSocket バッファー、ポーリング
• トラブルシューティングとサポートバンドル -- レビュー済みのサポート情報、二重認証のデバッグ、ツールが見つからない場合

開発

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

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

ライセンス

MIT