UniFi MCP Server

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

Claude などの AI アシスタントに UniFi Network および Protect のインフラストラクチャ管理・分析機能へのアクセスを提供する MCP (Model Context Protocol) サーバーです。

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

アップストリームからの改善点

• ローカルセッション認証ルーティングの修正 — UNIFI_MODE=local では、リクエストが従来のコントローラー API（/proxy/network）を Cookie + CSRF セッション認証で正しく使用するようになりました。アップストリームはモードに関係なく常に Integration API 経由でルーティングしていました。

• モード対応のベース URL 解決 — api_base_url は、無条件に Integration API エンドポイントを返すのではなく、設定された認証モードを尊重するようになりました。

• テストスイートの拡充 — 設定、ネットワーククライアントの動作、サーバーツール登録、Protect 連携をカバーする 57 件の成功テスト。

Related MCP server: UniFi MCP Server

機能

UniFi Network

• デバイス管理: UniFi デバイス（AP、スイッチ、ルーター）の一覧表示、再起動、位置特定、アップグレード

• クライアント管理: 接続中クライアントの監視、ブロック/ブロック解除、トラフィック統計の表示

• サイト管理: サイトの健全性、ネットワーク設定、VLAN、ワイヤレス設定の表示

• 統計と監視: イベント、アラーム、スピードテスト、DPI 統計

• AI を活用したインサイト: ネットワーク分析、最適化の推奨事項、トラブルシューティング

UniFi Protect

• カメラ管理: カメラの一覧表示、ステータス表示、ライブスナップショットの取得

• システム監視: NVR ステータス、カメラの健全性サマリー

• アクセサリ: ライト、センサー、チャイム、ビューアーの管理

• ライブビュー: 設定済みカメラビュー構成へのアクセス

マルチデバイスサポート

• 複数の UniFi デバイス（ゲートウェイ、NVR など）を設定可能

• 名前で特定のデバイスを指定可能 — すべてのネットワークおよび Protect ツールはオプションの device パラメーターを受け付けます

• デバイスごとの API キー: 設定済みの各デバイスは独自のキーで認証します

• デバイスをまたいだ Network サービスと Protect サービスの混在

認証モード

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

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

エージェントスキル

バンドルされているスキル（skills/ 内）は、このサーバー向けに実証済みのワークフローをエージェントに教えます。コントローラー固有の落とし穴（Network 10 で削除されたエンドポイント、ゾーンペアルール、WPA3 移行）も含みます。

完全なドキュメント: 使用ガイド、期待される結果、トラブルシューティング、新機能のリクエスト方法については SKILLS.md を参照してください。

クイックリファレンス

スキルの仕組み

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

• "インターネットが落ちた" → unifi-internet-down が WAN、モデム、ゲートウェイを診断

• "私の WiFi に誰がいる？" → unifi-whos-home がデバイスを一覧表示し、不明なデバイスにフラグを立てます

• "ネットワークを監査して" → unifi-network-audit が完全な健全性レポートを生成

• "新しいテレビをセットアップして" → unifi-setup-new-device が WiFi ペアリングを案内

書き込み時要承認スキル（上記にマークあり）はネットワークを変更します。変更を適用する前には必ず承認を求めます。

非技術者向けスキルは専門用語を避け、すべての技術用語をわかりやすい言葉に置き換え、破壊的な操作の前には確認を求めます。

インストール（プロジェクト単位）: .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+)

インストール

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 デバイスを構成します:

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

デバイス構成フィールド:

注: 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

クラウド API (api.ui.com)

Ubiquiti Cloud API アクセス用:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

unifi.ui.com → API セクションから 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
    }
  }
}

利用可能なツール

マルチデバイス管理

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

デバイス管理

• list_devices - すべての UniFi ネットワークデバイスを一覧表示

• get_device_details - 詳細なデバイス情報を取得

• restart_device - デバイスを再起動

• locate_device - LED を点滅させてデバイスを探す

• get_device_stats - パフォーマンス統計を取得

• upgrade_device - ファームウェアをアップグレード

• provision_device - 再プロビジョニングを強制

クライアント管理

• list_clients - 接続中のクライアントを一覧表示

• list_all_clients - 既知のすべてのクライアントを一覧表示（オフラインを含む）

• get_client_details - クライアントの詳細を取得

• block_client / unblock_client - クライアントをブロック/ブロック解除

• kick_client - クライアントを切断

• forget_client - 既知のクライアントから削除

• get_client_traffic - トラフィック統計を取得

• reserve_client_ip - DHCP 予約で IP を予約

サイト管理

• 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_wlan / update_wlan / delete_wlan - ワイヤレスネットワークを管理します

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - ゾーンベースのファイアウォールポリシーを管理します

• export_camera_clip - カメラの録画クリップをMP4としてエクスポートします（Protect）

• 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

• 「すべてのカメラを一覧表示して」

• 「カメラの健全性の概要を見せて」

• 「Front Doorカメラのスナップショットを取得して」

• 「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

新機能のリクエスト

• 新しいスキル: [Skill] プレフィックスを付けてイシューを開いてください — 問題、ワークフロー、期待される出力を説明してください

• スキルの修正: [Skill: skill-name] プレフィックスを付けてイシューを開いてください — 不足している点や壊れている点

• 新しいツール: [Tool] プレフィックスを付けてイシューを開いてください — UniFi APIエンドポイントと期待される形式を含めてください

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

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

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

• 認証情報は環境変数を介して渡されます — .env をコミットしないでください

• 自己署名証明書の場合、SSL検証はデフォルトで無効になっています

• サーバーは読み取り操作と安全な管理コマンドのみを公開します

• 破壊的操作（サイトの削除、ファクトリーリセット）は公開されていません

• APIキーは安全に保管し、定期的にローテーションしてください

ライセンス

MITライセンス

コントリビューション

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