unifi-mcp

UniFi MCP サーバー

mcp-name: io.github.mikeholownych/unifi-mcp

Claude などの AI アシスタントに、UniFi Network および Protect インフラストラクチャの管理・分析機能へのアクセスを提供する MCP（Model Context Protocol）サーバーです。ネイティブの MCP SDK 2 の MCPServer API（FastMCP 3 ではありません）を使用し、デフォルトでは stdio 経由で通信します。

クレジット： このプロジェクトは gbassaragh/Unifi-mcp のフォークとして始まり、その後、完全に独立したプロジェクトへと発展しました。優れた出発点を提供してくださった @gbassaragh に感謝します。

上流版からの改善点

• ローカルセッション認証のルーティングを修正 — UNIFI_MODE=local の場合、リクエストは従来のコントローラー API（/proxy/network）を Cookie と CSRF セッション認証で正しく使用するようになりました。上流版ではモードにかかわらず、常に Integration API 経由でルーティングされていました。
• モードに応じたベース URL の解決 — api_base_url は、Integration API エンドポイントを無条件に返すのではなく、設定された認証モードを反映するようになりました。
• テストスイートを拡充 — 設定、MCP 互換性、ランタイムの永続化、ネットワーククライアントの動作、サーバーのツール登録、Protect 連携を対象とした 250 件以上のテストが成功しています。

機能

UniFi Network

• デバイス管理： UniFi デバイス（AP、スイッチ、ルーター）の一覧表示、再起動、位置特定、アップグレード
• クライアント管理： 接続中のクライアントの監視、ブロック／ブロック解除、トラフィック統計の表示
• サイト管理： サイトのヘルス状態、ネットワーク構成、VLAN、ワイヤレス設定の表示
• 統計と監視： イベント、アラーム、速度テスト、DPI 統計
• AI を活用したインサイト： ネットワーク分析、最適化の推奨、トラブルシューティング

UniFi Protect

• カメラ管理： カメラの一覧表示、ステータスの確認、ライブスナップショットの取得
• システム監視： NVR のステータス、カメラのヘルス概要
• アクセサリー： ライト、センサー、チャイム、ビューアーの管理
• ライブビュー： 設定済みのカメラ表示レイアウトへのアクセス

複数デバイスのサポート

• 複数の UniFi デバイス（ゲートウェイ、NVR など）を設定できます
• 名前で特定のデバイスを指定できます — ネットワークと Protect のすべてのツールで、オプションの device パラメーターを使用できます
• デバイスごとの API キー：設定した各デバイスは、それぞれ独自のキーで認証されます
• 複数デバイスにわたって Network サービスと Protect サービスを組み合わせられます

イベントと安全な自動化

• Network と Protect のイベントを正規化し、オプションの SQLite ストレージで永続的に重複排除します
• 設定された各ソースを個別にポーリングし、サポートされていない機能を明示的に報告します
• 組み込みの間隔ジョブのみを実行します：poll_events、retry_webhook_deliveries、capture_observations、prune_runtime_data
• フィルタリングされ署名された HTTPS Webhook を、上限付きの再試行とデッドレター状態に対応して配信します
• 永続化、バックグラウンド自動化、プライベート Webhook の送信先は、デフォルトで無効になっています

認証モード

モード	認証	最適な用途
local_api_key	Integration API キー	推奨されるデフォルト設定。幅広い読み取りアクセス
local	ユーザー名／パスワードによるセッション	すべての機能へのアクセス：ファイアウォールルール、WLAN 設定、サイト設定、イベント、アラーム、DPI
cloud	api.ui.com キー	リモート／クラウド管理コントローラー

API キー（Integration API）を使用する場合、コントローラー機能の一部はレガシーセッション認証（UNIFI_MODE=local）でのみ利用できます。対象は、ネットワークイベント、アラーム、DPI 統計、速度テスト、WLAN 設定、ファイアウォールルール、ポートプロファイル、ルーティングテーブルです。これらの機能に対応するツールは、何も通知せずに失敗するのではなく、有効化方法を説明する明確なエラーを返します。インサイトツールは段階的に機能を縮退させ、データの制限を報告します。

ローカルアカウントに関する注意： MFA で保護されている SSO／Ubiquiti アカウントの管理者は、セッションログインを完了できません。UNIFI_MODE=local を使用するには、コンソールにローカル管理者を作成してください（ローカルアクセスのみに制限）。

エージェントスキル

同梱のスキル（skills/）では、このサーバーで実証済みのワークフローをエージェントに教えます。Network 10 で削除されたエンドポイント、ゾーンペアルール、WPA3 移行など、コントローラー固有の注意点も含まれます。

詳細なドキュメント：使い方、想定される結果、トラブルシューティング、新機能のリクエスト方法については、SKILLS.md を参照してください。

クイックリファレンス

スキル	種類	目的
unifi-network-audit	読み取り専用	サイト全体の監査：デバイス、クライアント、Wi-Fi の状態、ファイアウォール、構造化レポート
unifi-troubleshoot-client	読み取り専用	動作に問題のあるデバイスを診断：RF、ローミング、ブロック、IP 層
unifi-wifi-optimize	書き込みに承認が必要	チャネル計画、帯域幅、WPA3 移行、バンドステアリング — 承認が必要
unifi-grant-device-access	書き込みに承認が必要	デバイスに予約済み IP と、スコープを限定したゾーンファイアウォールアクセスを付与
unifi-internet-down	読み取り専用の一次切り分け	「インターネットがつながらない！」— 平易な言葉での障害診断、ISP へのエスカレーション用スクリプト
unifi-whos-home	読み取り専用	「Wi-Fi に接続しているのは誰？」— わかりやすい端末一覧、ランダム MAC アドレスを考慮した侵入者チェック
unifi-setup-new-device	書き込みに承認が必要	新しいデバイスをオンラインにする：ペアリング時の落とし穴（2.4GHz／WPA3）、名前付け、IP 予約
unifi-dns-triage	読み取り専用	「ping は通るのにサイトが開かない」— 名前解決と接続性の切り分け、内部 DNS の強制パターン
unifi-mdns-discovery	読み取り専用＋	VLAN 間で AirPrint／Cast が動作しない場合：mDNS リフレクション、IGMP／IPTV に関する注意点
unifi-port-forwarding	書き込みに承認が必要	セルフホスト型サービスの公開。ヘアピン NAT、CGNAT 検出、ゾーンポリシーの組み合わせを含む
unifi-vpn	書き込みに承認が必要	WireGuard／Teleport の設定と、ハンドシェイク／MTU／ゾーンポリシーの障害対応手順
unifi-firmware-campaign	書き込みに承認が必要	段階的なファームウェア更新：スナップショット、カナリア、検証、デバイスが応答しない場合の対応手順
unifi-mesh-backhaul	読み取り専用	離れた部屋で Wi-Fi が遅い場合：ワイヤレスアップリンク／ホップの診断、有線バックホールのガイダンス
unifi-ids-ips-triage	読み取り専用＋	脅威アラート：誤検知と実際の脅威の判別、抑制、IPS によるスループットへの影響
unifi-backup-migration	書き込みに承認が必要	バックアップに含まれる内容、移行の基本的な指針、移行前のスナップショット
unifi-network-map	ドキュメント作成	ラベル付きの永続的なトポロジー（ゾーン／VLAN／依存関係）を作成し、ほかのすべてのスキルの精度を高めます

スキルの仕組み

問題を自然な言葉で説明するだけで、エージェントがリクエストに適したスキルを選び、そのワークフローに従います。

• 「インターネットがつながりません」 → unifi-internet-down が WAN、モデム、ゲートウェイを診断します
• 「Wi-Fi に接続しているのは誰ですか？」 → unifi-whos-home がデバイスを一覧表示し、不明なデバイスに印を付けます
• 「ネットワークを監査してください」 → unifi-network-audit が詳細なヘルスレポートを作成します
• 「新しいテレビをセットアップしてください」 → unifi-setup-new-device が Wi-Fi のペアリングを案内します

書き込みが制限されたスキル（上記に記載）はネットワークを変更するため、変更を適用する前に必ず承認を求めます。

技術に詳しくないユーザー向けのスキルでは、専門用語を避け、すべての技術用語を分かりやすく説明し、影響の大きい操作を行う前に確認を求めます。

インストール（プロジェクトごと）：.claude/skills/ にコピーします。

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

使用方法、期待される結果、トラブルシューティング、新しい機能をリクエストする方法については、SKILLS.md をご覧ください。

スキルでは MCP ツールをプレーンな名前（get_firewall_policies、…）で参照します。 MCP クライアントが自動的にプレフィックスを付けます。

対応ハードウェア

• UniFi Dream Machine（UDM、UDM-Pro、UDM-SE）
• UniFi Cloud Gateway（UCG-Ultra、UCG-Fiber）
• UniFi Network Video Recorder（UNVR、UNVR-Pro）
• UniFi Network Application（セルフホスト）
• 従来の Cloud Key（Gen1、Gen2、Gen2+）

制限事項と対応バージョン

このサーバーは、信頼できるローカルネットワーク上での運用を想定しており、IP アドレスを使って UniFi コンソールに接続します。これを踏まえ、以下の点にご注意ください。

• TLS 検証はデフォルトで無効です（UNIFI_VERIFY_SSL=false）。UniFi OS には自己署名証明書が付属しており、コントローラーには LAN 上の IP アドレスで接続するため、証明書検証は失敗することが想定されています。UNIFI_VERIFY_SSL=true を有効にするのは、コントローラーが CA によって信頼された証明書を提示する場合に限ってください。
• 起動時にデバイスが設定されていなくても問題ありません。 UNIFI_* 認証情報が指定される前（環境変数でデプロイおよび設定する場合など）でも、サーバーは起動してすべてのツールを公開します。デバイスに依存するツールを呼び出すと、デバイスが設定されるまで明確な No device configured エラーが返されます。
• スコープの適用対象はリモートトランスポートのみです。 Streamable HTTP 経由で実行する場合、すべての tools/call は読み取り／書き込み／管理者の OIDC スコープによって制限されます。また、分類されていないツールがあると起動に失敗します。stdio（ローカル IPC）では認証は不要です。stdio は信頼できるローカルプロセスであると想定されます。
• Integration API キーには制限があります。 一部のコントローラー機能は、レガシーセッション認証（UNIFI_MODE=local）でのみ利用できます。対象はネットワークイベント、アラーム、DPI 統計、速度テスト、WLAN／ファイアウォール設定、ポートプロファイル、ルーティングテーブルです。これらのツールは、有効化方法を説明する明確なエラーを返します。
• 最近の UniFi OS／Network／Protect でテスト済みです。 レガシーエンドポイントが削除された新しいコントローラー（例：UniFi Network 10 ではアラーム／イベントのエンドポイントが削除されています）では、エラーを返すのではなく、機能を縮退させて対応します。
• コントローラーのバックアップの代わりにはなりません。 スナップショットとレポートは読み取り専用のエクスポートであり、コントローラーの設定や復元は行いません。

インストール

uv を使用する場合（推奨）

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

pip を使用する場合

pip install -e .

設定

プロジェクトのルートに .env ファイルを作成するか、環境変数を設定します。すべてのオプションについては .env.example をご覧ください。

UNIFI_CACHE_TTL は、クライアントインスタンス間で共有される GET キャッシュの有効期間を制御します（デフォルト：30 秒）。変更の検証では、デフォルトで 0.5、1、2、2 秒の指数的な遅延を挟みながら、最新の状態を 5 回読み取ります。コントローラーの収束が通常より遅い、または速い場合は、UNIFI_MUTATION_VERIFY_ATTEMPTS、UNIFI_MUTATION_VERIFY_INITIAL_DELAY、UNIFI_MUTATION_VERIFY_MAX_DELAY で調整してください。

オプションのランタイム永続化

SQLite によるランタイム永続化はデフォルトで無効です。ランタイム状態を永続化する必要がある場合にのみ有効にしてください。

UNIFI_RUNTIME_ENABLED=true

デフォルトでは、データベースは UNIFI_DATA_DIR の下にある runtime.db です。UNIFI_DATA_DIR が設定されていない場合、サーバーは XDG データ規約に従います。XDG_DATA_HOME が絶対パスの場合は $XDG_DATA_HOME/unifi-mcp、それ以外の場合は ~/.local/share/unifi-mcp です。したがって、デフォルトのデータベースは $XDG_DATA_HOME/unifi-mcp/runtime.db または ~/.local/share/unifi-mcp/runtime.db になります。

必要に応じて、明示的なデータディレクトリまたはデータベースパスを設定してください。

UNIFI_DATA_DIR=/var/lib/unifi-mcp
UNIFI_RUNTIME_DATABASE=/var/lib/unifi-mcp/runtime.db

UNIFI_DATA_DIR と UNIFI_RUNTIME_DATABASE は、絶対パスとして解決される必要があります。UNIFI_RUNTIME_DATABASE は、UNIFI_DATA_DIR から導出されるデータベースパスを上書きします。

イベント、スケジュール、Webhook

ランタイム永続化を有効にすると、イベントの保存と管理ツールが利用可能になりますが、バックグラウンド処理は開始されません。スケジューラーは別途有効にしてください。

UNIFI_RUNTIME_ENABLED=true
UNIFI_AUTOMATION_ENABLED=true

イベントの取り込みは、機能に基づくポーリングであり、UniFi のあらゆる環境でプッシュに対応していることを意味するものではありません。

• Network のイベントポーリングには、UNIFI_MODE=local による従来のローカルセッション認証が必要です。
• Protect のイベントポーリングには、各 Protect デバイスで username と password を設定する必要があります。
• Integration API とクラウド版 Network の構成は、イベントポーリング非対応として報告されます。
• ポーリングでは、重複期間と永続的なソースキーによる重複排除を用いるため、タイムスタンプの境界によってレコードが重複することはありません。

スケジュールで実行できるのは、poll_events、retry_webhook_deliveries、capture_observations、または prune_runtime_data のみです。スケジュールと Webhook の変更には confirm=true が必要です。任意の MCP ツール名、コマンド、インポート、式は拒否されます。

Webhook の送信先には HTTPS を使用し、リダイレクトには追従しません。また、各試行の前に名前解決と検証を行います。ループバック、プライベート、リンクローカル、マルチキャスト、および予約済みのアドレスは、UNIFI_WEBHOOK_ALLOW_PRIVATE=true が設定されていない限り拒否されます。専用の Webhook クライアントでは、UniFi コントローラーが自己署名証明書を使用している場合でも、証明書の検証を維持します。

署名シークレットが SQLite や MCP の引数に保存されることはありません。シークレットをサーバー環境に設定し、secret_env_name には環境変数名のみを渡してください。

WEBHOOK_SECRET_AUTOMATION='replace-with-a-random-secret'

便利なツールには、get_event_polling_status、poll_events_now、list_runtime_events、create_interval_schedule、run_schedule_now、list_job_runs、create_webhook_destination、test_webhook_destination、list_webhook_deliveries があります。再試行可能なジョブと Webhook の失敗には、上限付きの指数バックオフが適用されます。再試行上限に達した配信は dead_letter 状態になります。

ポータブルスナップショットとレポート

ポータブルスナップショットは、サポート対象の読み取り API から構成される、バージョン管理された正規化 JSON エクスポートです。ソースのスコープ、明示的なデータ制限、Network／Protect のインベントリー、ネットワーク、WLAN メタデータ、ファイアウォールのルール／ポリシーのメタデータが含まれます。認証情報、API キー、Cookie、認証ヘッダー、WLAN のパスフレーズは、構造上含まれません。

# Optional absolute override; defaults to <UNIFI_DATA_DIR>/exports
UNIFI_EXPORT_DIR=/var/lib/unifi-mcp/exports

エクスポートツールには任意のパスではなく、ファイル名のみを指定できます。パストラバーサルとシンボリックリンクは拒否され、ファイルは 0600 の権限でアトミックに書き込まれます。export_portable_snapshot には SHA-256 のコンテンツチェックサムが含まれます。verify_snapshot は、不正な形式、切り詰め、改変が行われたスナップショットを検出します。export_network_report は、同じ厳格なモデルを、エスケープ済みのスタンドアロン HTML または数式インジェクション対策済みの CSV として出力します。

コントローラーファミリーごとのエンドポイントと、安全な復元検証が確認されるまでは、コントローラーのネイティブバックアップのダウンロードと復元は、意図的に利用不可として報告されます。ポータブルスナップショットは評価と支援付きの再構成をサポートしますが、復元可能なネイティブコントローラーバックアップとしては扱われません。

履歴と Prometheus

ランタイム永続化が有効な場合、capture_observations_now は、サイトのヘルス状態、デバイス／クライアント数、トラフィックの合計、Protect カメラのヘルス状態を、上限付きの集計データとして保存します。クライアントごとの履歴やパケットフローテレメトリーは保存しません。query_observation_trends は、収集されなかった期間について値を補間して作り出すことなく、present=false を含む上限付きの UTC バケットを返します。

Prometheus サポートは基本の依存関係セットには含まれず、デフォルトではリスナーを起動しません。

uv sync --extra observability
UNIFI_RUNTIME_ENABLED=true
UNIFI_PROMETHEUS_ENABLED=true
UNIFI_PROMETHEUS_HOST=127.0.0.1

メトリクスには、コントローラー、サイト、クライアント、MAC、IP、SSID のラベルを含まない固定名を使用します。ループバック以外にバインドするには、UNIFI_PROMETHEUS_ALLOW_REMOTE=true に加え、ベアラートークンを含む環境変数の名前を指定する UNIFI_PROMETHEUS_BEARER_TOKEN_ENV が必要です。トークン値はリクエスト時に読み込まれ、永続化されることはありません。

クライアントの整理と QoS プレビュー

ランタイム永続化が有効な場合、クライアントには複数のローカルタグと、最大 1 つのローカルグループを設定できます。所属情報は、安定したクライアント MAC から導出した、コントローラー／サイトのスコープに限定された SHA-256 値をキーとして保存されます。生の MAC アドレスや変更可能なクライアント名は保存されません。正確な名前とホスト名は一時的な検索ヒントとして使用できますが、曖昧な一致は拒否されるため、正確な MAC アドレスを指定する必要があります。タグとグループはクライアント名を変更しても維持され、コントローラー設定は変更しません。

整理情報の変更には confirm=true が必要です。set_client_tags、create_client_group、assign_client_group、list_client_groups、list_clients_by_organization を使用して、ローカルメタデータを管理または照会できます。

plan_client_qos_policy は、1 つのクライアント、タグ、またはグループで選択された対象の、決定論的な 1 時間有効のスナップショットを永続化します。対象台帳にはスコープ限定の一方向クライアントキーのみが含まれ、将来の再開可能な対象ごとの適用状態に対応します。このリリースには、検証済みのコントローラー QoS アダプターはありません。get_client_qos_capabilities はその制限を報告し、apply_client_qos_policy はコントローラーへの変更を行わずに終了します。ローカルタグが QoS ポリシーを示すことはありません。

信頼されたプラグイン

Python のエントリーポイント名が UNIFI_PLUGIN_ALLOWLIST に明示的に記載されていない限り、プラグインは無効です。プラグインはサーバープロセス内で信頼されたローカルコードとして実行され、サンドボックス化されません。必須プラグインも許可リストに登録する必要があり、UNIFI_PLUGIN_REQUIRED に記載します。必須プラグインが見つからない場合、互換性がない場合、重複している場合、または読み込みに失敗した場合は、起動が停止します。任意のプラグインの読み込み失敗は分離され、get_plugin_status で確認できます。

プラグインは API バージョン 1 と unifi_mcp.plugins エントリーポイントグループを使用します。

[project.entry-points."unifi_mcp.plugins"]
example = "example_package.plugin:plugin"

読み込まれるオブジェクトは api_version = 1 を宣言し、register(registry) を実装します。レジストリは、明示的な read、write、admin のいずれかのスコープを指定する register_tool に加え、名前付きコレクター、JobDefinition ジョブ、通知シンク、バイト列を返すレポートレンダラーに対応しています。プラグイン名でコアツールやジョブを上書きすることはできません。

ストリーム可能な HTTP と OIDC

stdio は引き続きデフォルトのローカルプロセストランスポートであり、ID プロバイダーの設定は不要です。リモート MCP は UNIFI_TRANSPORT=streamable-http の場合にのみ起動します。宣言された認証機能を uv sync --extra oidc でインストールし、完全な OIDC 設定を指定してください。

UNIFI_TRANSPORT=streamable-http
UNIFI_HTTP_HOST=127.0.0.1
UNIFI_HTTP_PORT=8000
UNIFI_HTTP_PATH=/mcp
UNIFI_HTTP_PUBLIC_URL=https://mcp.example.com/mcp
UNIFI_OIDC_ISSUER=https://identity.example.com
UNIFI_OIDC_AUDIENCE=unifi-mcp
UNIFI_OIDC_ALGORITHMS=RS256

ディスカバリー情報と JWKS データは、タイムアウトを設定して HTTPS 経由で取得され、デフォルトで 5 分間キャッシュされます。未知の署名鍵が使われた場合は、1 回だけ再取得します。トークンは、許可された非対称アルゴリズム、署名、発行者、オーディエンス、有効期限、サブジェクト、スコープについてローカルで検証されます。認可ヘッダー、トークン、クレーム、署名鍵は、ログにも永続データにも記録されません。

すべての HTTP ツール呼び出しには UNIFI_OIDC_READ_SCOPE（デフォルトは unifi:read）が必要です。変更操作にはさらに UNIFI_OIDC_WRITE_SCOPE が必要です。ランタイム管理とプラグインのステータス確認には UNIFI_OIDC_ADMIN_SCOPE が必要です。既存の confirm=true による制約も引き続き適用されます。ループバック以外にバインドするには、さらに UNIFI_HTTP_ALLOW_REMOTE=true が必要です。本番環境では、宣言された HTTPS 公開 URL で TLS を終端してください。

複数デバイスの設定（推奨）

異なるサービスを使用する複数の UniFi デバイスを設定します。

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

デバイス設定フィールド：

フィールド	説明	デフォルト
name	デバイスを指定するためのわかりやすい名前	（必須）
url	UniFi デバイスのベース URL	（必須）
api_key	UniFi OS Control Plane の API キー	（必須）
services	配列：["network"]、["protect"]、または両方	["network"]
site	ネットワーク操作用のサイト名	"default"
verify_ssl	SSL 証明書を検証するかどうか	false
username	Protect イベント用のユーザー名（任意）	null
password	Protect イベント用のパスワード（任意）	null

注： username と password のフィールドが必要なのは、Protect イベントツール（モーションイベント、スマート検知）のみです。基本的なカメラ操作には API キーだけで対応できます。

API キーを作成するには：

1. UniFi コントローラーにログインします
2. Settings → Control Plane → API に移動します
3. 適切な権限を付与した新しい API キーを作成します

従来の単一デバイス設定

後方互換性のため、単一デバイスの設定も引き続きサポートされています。

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

ローカルセッション認証（従来方式）

ユーザー名とパスワードによる認証で、すべての機能にアクセスする場合：

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API（api.ui.com）

Ubiquiti Cloud API にアクセスする場合：

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

API キーは unifi.ui.com → API セクションから取得できます。

Claude Desktop での使用方法

Claude Desktop の設定に追加します（Linux の場合は ~/.config/claude/claude_desktop_config.json、macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code / opencode での使用方法

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

または opencode.json に追加します：

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

利用可能なツール

サーバーの状態

• get_server_health - サーバーのバージョン、stdio トランスポート、設定済みサービス数、および任意の永続化ステータスを報告します。応答には、認証情報、コントローラーのアドレス、デバイス名、データベースのパスは意図的に含まれません。

複数デバイスの管理

• list_unifi_devices - 設定済みの UniFi デバイスとそのサービスをすべて一覧表示します

デバイスの管理

• list_devices - UniFi ネットワークデバイスをすべて一覧表示します
• get_device_details - デバイスの詳細情報を取得します
• restart_device - デバイスを再起動します
• locate_device - LED を点滅させてデバイスの場所を特定します
• get_device_stats - パフォーマンス統計を取得します
• upgrade_device - ファームウェアをアップグレードします
• provision_device - プロビジョニングを強制的にやり直します
• get_device_ports - スイッチ／ゲートウェイのポート設定とリンク状態を一覧表示します
• set_device_port - 1 つのポートを設定します。confirm=true が必要で、コントローラーからの読み戻しを検証します

クライアントの管理

• list_clients - 接続中のクライアントを一覧表示します
• list_all_clients - オフラインのものも含め、既知のクライアントをすべて一覧表示します
• get_client_details - クライアントの詳細を取得します
• block_client / unblock_client - クライアントをブロック／ブロック解除します
• kick_client - クライアントの接続を切断します
• forget_client - 既知のクライアントから削除します
• get_client_traffic - トラフィック統計を取得します
• reserve_client_ip - DHCP 予約で IP アドレスを予約します
• get_client_organization / set_client_tags - 永続的なローカルタグを読み取る、または置き換えます
• create_client_group / delete_client_group - ローカル限定グループを管理します
• assign_client_group / list_client_groups - 単一グループへの所属を管理、確認します
• list_clients_by_organization - 決定的なタグまたはグループの対象セットを解決します
• get_client_qos_capabilities - 検証済みのコントローラー QoS 対応状況を報告します
• plan_client_qos_policy / apply_client_qos_policy - QoS の対象をプレビューし、検証済みアダプターがある場合にのみ適用します

サイト管理

• list_sites - すべてのサイトを一覧表示
• get_site_health - サイトの健全性ステータスを取得
• get_site_settings - サイト設定を取得
• get_sysinfo - システム情報を取得
• get_networks - ネットワーク／VLAN 設定を取得
• get_wlans - 無線ネットワーク設定を取得
• get_port_profiles - スイッチポートプロファイルを取得
• get_firewall_rules - 従来のファイアウォールルールを取得
• get_firewall_policies - ゾーンベースのファイアウォールポリシーを取得（UniFi Network 9+）
• get_routing_table - ルーティングテーブルを取得
• get_port_forwards - ポートフォワーディングルールを取得
• create_port_forward / delete_port_forward - ポートフォワーディングを管理

設定管理（書き込み）

• create_network / update_network / delete_network - ネットワークと VLAN を管理します。各操作には confirm=true が必要で、コントローラーからの読み戻しを検証します
• create_wlan / update_wlan / delete_wlan - 無線ネットワークを管理
• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - ゾーンベースのファイアウォールポリシーを管理
• export_camera_clip - UNIFI_EXPORT_DIR 内に MP4 をエクスポートします。confirm=true が必要です
• get_all_sites_health - すべてのサイトの健全性の概要

データを削除したり、サービスに支障をきたしたりする書き込みツールは、確認を必須とするか、MCP アノテーションで破壊的な操作としてフラグ付けされています。

統計とモニタリング

• get_network_health - ネットワーク全体の健全性
• get_recent_events - 最近のイベント
• get_alarms - アクティブなアラーム
• archive_all_alarms - すべてのアラームをアーカイブ
• run_speed_test - 速度テストを開始
• get_speed_test_status - 速度テストの結果を取得
• get_dpi_stats - DPI 統計
• get_traffic_summary - トラフィックの概要

AI インサイトツール

• analyze_network_issues - 問題を包括的に分析
• get_optimization_recommendations - 設定に関する推奨事項
• get_client_experience_report - クライアント品質の指標
• get_device_health_summary - デバイスの健全性の概要
• get_traffic_analysis - トラフィックパターンの分析
• get_all_sites_health - すべてのサイトの健全性の概要

マルチサイトオーケストレーション

• get_global_inventory - すべてのコントローラーにまたがる統合デバイスインベントリ
• get_global_health - すべてのコントローラーにまたがる健全性レポートの集約
• get_global_client_summary - すべてのコントローラーにまたがるクライアント数、上位通信クライアント、ブロックされたクライアント
• troubleshoot_client - クライアントの詳細なトラブルシューティング

UniFi Protect

• list_cameras - 接続ステータスとともにすべてのカメラを一覧表示
• get_camera_details - カメラの詳細情報を取得
• get_camera_snapshot - ライブスナップショットを取得（base64 JPEG）
• get_protect_system_info - NVR システム情報を取得
• get_camera_health_summary - 問題を含むカメラの健全性の概要
• get_liveviews - 設定済みのライブビューのレイアウトを取得
• get_protect_accessories - ライト、センサー、チャイム、ビューアーを一覧表示

UniFi Protect イベント（ユーザー名／パスワードが必要）

• get_motion_events - 最近のモーションイベントを取得
• get_smart_detections - スマート検知イベントを取得（人物、車両、動物、荷物）
• get_protect_event_summary - 種類別の全イベントの概要
• get_recent_protect_activity - 最近のアクティビティの簡単な概要

会話例

MCP サーバーに接続すると、Claude に次のように質問できます。

ネットワーク管理

• 「UniFi デバイスをすべて一覧表示して」
• 「現在のネットワークの健全性はどうなっていますか？」
• 「ネットワークに問題がないか分析して」
• 「どんな最適化の推奨事項がありますか？」
• 「クライアントのエクスペリエンス指標を見せて」
• 「MAC アドレスが aa:bb:cc:dd:ee:ff のクライアントをトラブルシューティングして」
• 「最も多くの帯域幅を使用しているクライアントはどれですか？」
• 「ファームウェアのアップデートが必要なデバイスはありますか？」
• 「最近のネットワークイベントを見せて」
• 「速度テストを実行して」

UniFi Protect

• 「カメラをすべて一覧表示して」
• 「カメラの健全性の概要を見せて」
• 「玄関のカメラのスナップショットを取得して」
• 「NVR のステータスはどうなっていますか？」
• 「接続が切れているカメラはありますか？」
• 「Protect のアクセサリーを見せて」

Protect イベント（認証情報が必要）

• 「最近のモーションイベントを表示して」
• 「過去24時間に発生したスマート検知を教えて」
• 「今日、人を検知しましたか？」
• 「過去1週間のイベント概要を教えて」
• 「Front Door カメラの最近のアクティビティを表示して」

複数デバイス

• 「設定済みの UniFi デバイスを一覧表示して」
• 「NVR のカメラを表示して」
• 「メインゲートウェイのネットワークの状態を取得して」

開発

テストの実行

uv run pytest

コードのフォーマット

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

オプションのランタイム永続化を有効にするには、イメージの書き込み可能な /data ディレクトリに名前付きボリュームをマウントします。

docker run -i --rm \
  --env-file .env \
  --env UNIFI_RUNTIME_ENABLED=true \
  --env UNIFI_DATA_DIR=/data \
  --volume unifi-mcp-data:/data \
  unifi-mcp

--rm は停止したコンテナを削除しますが、名前付きボリューム unifi-mcp-data は残り、後続の実行でも /data/runtime.db を保持します。

新機能のリクエスト

• 新しいスキル：[Skill] をプレフィックスとして issue を作成し、問題、ワークフロー、期待する出力を説明してください。
• スキルの変更：[Skill: skill-name] をプレフィックスとして issue を作成し、不足している点や動作しない点を説明してください。
• 新しいツール：[Tool] をプレフィックスとして issue を作成し、UniFi API エンドポイントと期待する形式を記載してください。

詳細なコントリビューションガイドラインについては、SKILLS.md を参照してください。

リリース履歴については CHANGELOG.md を、コントリビューションについては CONTRIBUTING.md を参照してください。

セキュリティに関する注意事項

• 認証情報は環境変数を介して渡します。.env を決してコミットしないでください。
• TLS 検証はデフォルトで無効です（UNIFI_VERIFY_SSL=false）。このサーバーは、自己署名証明書を使用し、IP アドレスでアクセスする UniFi コンソールに対して、信頼できる LAN 上で実行するよう設計されているためです。CA が信頼する証明書を使用する場合にのみ有効にしてください。
• stdio（ローカル IPC）では、トランスポートは信頼できるローカルプロセスであることを前提としているため、認証は不要です。Streamable HTTP では、すべてのツール呼び出しで適切な読み取り／書き込み／管理スコープを持つ有効な OIDC トークンが必要となり、サーバー側で適用されます。
• サーバーは読み取りツールと書き込みツールの両方を公開します。
• 破壊的、または中断を伴うツールには注釈が付与され、実装されている場合は明示的な確認が必須です。注釈をどのように表示または扱うかは、MCP クライアントが決定します。
• 工場出荷時設定へのリセットなど、特に危険な操作は公開していません。
• API キーは安全に保管し、定期的にローテーションしてください。

ライセンス

MIT License

コントリビューション

コントリビューションを歓迎します。issue を作成するか、プルリクエストを送信してください。