UniFi Network MCP

UniFi Network MCP Server

AI アシスタントやその他の MCP 対応クライアント向けに、UniFi Network Controller の 210 個のツールを公開する MCP サーバーです。クライアント、デバイス、ファイアウォールルール、VLAN、VPN、Traffic Flows、統計情報などを、デフォルトで安全な権限設定と、すべての変更操作に対する確認前のプレビューで照会できます。

既存の AI アシスタントやその他の MCP 対応クライアントで UniFi Network ツールが必要な場合は、このサーバーを使用してください。自動化サービス、コード実行ランタイム、MCP アダプターなど、HTTP 経由で連携するソフトウェアでは、REST と GraphQL による読み取り、アクション、SSE イベントに unifi-api-server を使用してください。呼び出し元のアプリケーションは、生成されたコードをサンドボックス化し、リソース制限を適用する必要があります。

インストール

Claude Code（推奨）

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

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

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

/unifi-network:unifi-network-setup

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

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

Codex

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

codex plugin marketplace add sirkirby/unifi-mcp

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

PyPI / Docker

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

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

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

使用例

次のマイナーリリースで承認されている MAC 引数名の変更については、MAC パラメーターの移行ガイドを参照してください。

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

「Guest VLAN 上のすべてのクライアントについて、信号強度とデータ使用量を表示してください」

「IoT デバイスが午前 0 時から午前 6 時までインターネットに接続できないようにするファイアウォールルールを作成してください」

「今週、最も多くクライアントが切断されたアクセスポイントはどれですか？」

「ファイアウォールポリシーを監査してください。冗長または競合するルールはありますか？」

「192.168.1.45 のデバイス名を『Living Room TV』に変更して、トラフィック統計を表示してください」

「過去 24 時間にネットワークで何が変わりましたか？新しいクライアントと設定変更を表示してください」

「過去 1 時間の最大トラフィックフローを表示し、誰が何と通信したかを要約してください」

すべての変更操作（ファイアウォールルール、デバイスの変更、クライアントのブロック）では、プレビューしてから確認するフローを使用します。適用前に、何が変更されるかを正確に確認できます。

V2 NAT ルール

unifi_list_nat_rules と unifi_get_nat_rule は V2 NAT ルールを読み取ります。作成、更新、削除、切り替えの各ツールには Network セッションの認証情報が必要で、V2 NAT ルール ID を使用します。ポート転送 ID および Integration API ID とは異なります。公開されている書き込み操作では、DNAT、SNAT、MASQUERADE を、IPv4、tcp_udp または all、NONE または ADDRESS_AND_PORT のフィルターとともに使用できます。作成時のデフォルトは enabled=false です。作成されたルールには手動作成かつ事前定義なしのマークが付けられ、読み取り時には両方の値が確認されます。既存ルールの origin が欠落しているか、手動作成でない場合、これらのツールでは編集できません。 変換後の port が指定された SNAT ルールでは、source_filter.port が必要です。コントローラーはポートの対応関係を検証します。このソースポートが欠落した既存ルールは、これらのツールで編集する前に、同じ更新内で修正する必要があります。切り替えでは明示的な enabled ブール値を指定するため、同じリクエストを繰り返しても何も行われません。IPv6、PPPoE、反転／除外マッチング、その他のフィルターバリエーションは、公開されている書き込み操作で検証されていません。 型が未検証の既存ルールでは、同じリクエストで型を検証済みのものに変更する場合でも、セレクターの編集は拒否されます。

MCP の更新プレビューには、最新の状態を反映した変更前と変更後のマージ結果が表示されます。確認時には状態を再度取得し、最大 1 回の全置換を送信した後、永続化を確認します。削除時には、最新の状態でルールが存在しないことを確認します。コントローラーの応答または読み戻しが不確かな場合は、再試行する前にルール一覧を確認してください。取得から PUT までの間にコントローラーで同時編集が発生すると、V2 NAT には条件付き置換機能がないため、その編集が上書きされる可能性があります。これらの確認で証明されるのは保存された設定であり、パケットレベルでの適用ではありません。既存の Core NAT メソッドは戻り値の形式を維持します。コントローラーへの変更操作で例外が発生した場合は、生の応答テキストの代わりに、安全で固定されたガイダンスが示されるようになりました。

承認済みのパケットテストには、IPv4 DNS リダイレクトのレシピを使用してください。単一のクライアントと合成宛先を対象とし、同一サブネット内の戻りトラフィックとクリーンアップも含まれます。

設定

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

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

# Server-specific variables (recommended)
UNIFI_NETWORK_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_NETWORK_USERNAME=admin         # Local admin username
UNIFI_NETWORK_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_NETWORK_API_KEY=             # UniFi API key (inventory and explicit Integration API tools)
# UNIFI_NETWORK_PORT=443             # Controller HTTPS port
# UNIFI_NETWORK_SITE=default         # UniFi site name
# UNIFI_NETWORK_VERIFY_SSL=false     # SSL certificate verification
# UNIFI_NETWORK_WEBSOCKET_ENABLED=true   # Real-time event listener feeding unifi_recent_events
# UNIFI_NETWORK_EVENT_BUFFER_SIZE=100    # Positive ring buffer capacity; invalid values prevent startup
# UNIFI_NETWORK_EVENT_BUFFER_TTL=300     # Positive lifetime in seconds; invalid values prevent startup

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

API キーのインベントリとセッション認証

デバイス、アクティブクライアント、ネットワーク、および WLAN の一覧には、ユーザー名/パスワードなしで UNIFI_NETWORK_API_KEY を設定します。同じツールが利用可能な読み取りパスを選択するため、重複する API キーツールは必要ありません。有効なセッション認証情報も設定されている場合、既存のセッションパスが引き続き優先されます。

レガシーインベントリエンドポイントで API キーを受け入れるコントローラーでは、通常の ID とフィールドが保持されます。これは UniFi OS プロキシを使用して Network 10.6.106 で検証済みです。サポートされる最小ファームウェアは確定していません。その他のコントローラーは、その API が利用可能な場合、パブリック Integration インベントリのフォールバックを使用できます。パブリックインベントリはフィールドとネットワークのカバレッジがより狭くなります（たとえば、WAN/VPN ネットワークが存在しない場合があります）。結果は source_api=integration を識別し、パブリック UUID を integration_id として公開します。これは決してレガシーリソース ID として公開されません。これらの UUID をレガシーの詳細/更新ツールに渡さないでください。欠落しているレガシーフィールドは不明です。したがって、API GraphQL プロジェクションでは、利用できない enabled、wired、guest フラグに null を許可します。クライアントはこれらの null を処理する必要があります。

履歴クライアント（include_offline=true）、完全な詳細、レガシーのミューテーション、および Network websocket は、依然としてそれぞれがサポートするレガシー/セッションパスを必要とします。API キーのレガシートランスポートは、検証済みのインベントリ GET リクエストに制限されています。読み取りの成功は書き込みの権限を意味しません。DPI ルックアップやファイアウォールの順序付けなどの明示的な Integration ツールは、それぞれ独自の API キー契約を保持します（レガシーのゾーン ID 解決にもセッションが必要です）。Protect は依然としてセッションブートストラップを必要とし、パブリックセッターには追加の API キーが必要です。Access は独立した API トークンとプロキシセッションのパスを維持します。ディスカバリは local_only、api_key_only、either、または both を報告します。これらは要件を表すものであり、設定された認証情報が正常に認証されたことの証明ではありません。

MCP レスポンスサイズ

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

遅延読み込みメタツール（*_tool_index、*_execute、*_batch、*_batch_status、および遅延専用の *_load_tools）はコンテンツのみのままです。これらは上記の 2025-06-18 より前のプロトコルカテゴリではありません。構造化された内部結果の場合、*_execute と *_batch_status は、ネストされたトランスポートペアではなく、content に 1 つの正規化された JSON ペイロードを公開します。コンテンツのみの execute 結果は変更されません。レスポンスモードはこれらのメタツールを structuredContent に変換しません。

Network はまた、デフォルトで 2 つの大きなソースレスポンスを制限します。unifi_get_dashboard は summary=true を使用し、unifi_list_rogue_aps は最大 100 レコードの要約されたページを返します。選択したダッシュボードまたは不正 AP データの完全なデータを要求するには、summary=false を渡してください。

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

ネットワークツールは、MCP クライアントにデータを返す前に、既知の秘密情報を含むフィールドをデフォルトでマスキングします。対象には、WLAN のパスフレーズ、VPN の鍵情報、VPN 設定全体のデータ、SNMP コミュニティ文字列、SNMPv3 パスワード、デバイスの SSH 認証情報、管理キーが含まれます。これらは raw/detail 応答と変更プレビューでマスキングされます。生の値が必要な場合は、信頼できるローカル管理プロセスで UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false を設定するか、グローバルポリシーフラグ UNIFI_REDACT_SENSITIVE_FIELDS=false を設定してマスキングを無効にしてください。

確定した Network/WLAN および VPN 状態の書き込みでは、コントローラーからデータを再取得し、正確な persisted_fields、unchanged_fields、dropped_fields、coerced_fields を報告します。すでに要件を満たしている変更不要のフィールドは unchanged_fields に表示され、書き込みの失敗が部分的な成功として扱われることはありません。success: false かつ mutation_applied: true の応答は、コントローラーが変更を受け付けたものの、正確には永続化されなかったことを意味します。これはロールバックではなく、部分的な書き込みである可能性があります。再試行または補正変更を適用する前に、partial_success と details_after_attempt を確認してください。

unifi_update_vpn_server_alternate_address は、server_id、部分的な update_data オブジェクト、confirm（デフォルトは false）を使用して、WireGuard サーバーのアドバタイズアドレスを更新します。受け付けるフィールドは alternate_address_enabled（ブール値）と alternate_address（URI、ポート、パスを含まないホスト名または IPv4 アドレス）です。有効化するには、統合後の設定に有効なアドレスが必要です。無効化する場合、置き換えの値も指定しない限り、保存されているアドレスは維持されます。null および不明なフィールドは拒否されます。サーバーの読み取りでは同じ名前が公開され、コントローラーに値がない場合は null が返されます。

この操作には Network セッションの認証情報と、VPN_SERVERS の UPDATE ポリシーゲートが必要です。MCP のプレビューには最新の変更前後の値が表示されます。API アクションのプレビューには送信された引数のみが表示され、有効状態の検証は実行時に行われます。確定した更新ではレコード全体を再取得し、無関係なフィールドを維持したうえで、書き込み後に要求したフィールドを検証します。レコード全体の PUT は、同時編集と競合する可能性があります。転送または読み戻しの結果が不確定な場合は mutation_applied: null が返されます。再試行する前にサーバーを確認してください。プレビューと結果には、公開されている 2 つの代替アドレスフィールドのみが含まれます。その他の VPN サーバータイプは、この検証済み書き込みの対象外です。

実行

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

# Docker
docker run -i --rm \
  -e UNIFI_NETWORK_HOST=192.168.1.1 \
  -e UNIFI_NETWORK_USERNAME=admin \
  -e UNIFI_NETWORK_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-network-mcp:latest

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-network-mcp"],
      "env": {
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_USERNAME": "admin",
        "UNIFI_NETWORK_PASSWORD": "your-password"
      }
    }
  }
}

エージェントスキル

Claude Code 経由でインストールすると、ネットワークプラグインには、ネットワーク管理に特化したワークフローで Claude の機能を拡張する 3 つのエージェントスキルが含まれます。

ネットワークのヘルスチェック

トリガー：「ネットワークの状態を確認」「何がダウンしているか」「ヘルスチェックを実行」「ネットワークのステータス」

単一の unifi_batch 呼び出しで、システム情報、ネットワークの健全性、デバイス一覧、アクティブなアラームを含む診断スナップショット全体を収集し、構造化されたヘルスレポートを作成します。デバイス状態コード、アラームの種類と重大度レベル、ヘルスサブシステムの診断（WAN → LAN → WLAN → VPN の優先順位）に関する参考資料も含まれます。

ファイアウォールマネージャー

トリガー：「トラフィックをブロック」「ファイアウォールルールを作成」「IoT の分離を設定」「コンテンツフィルタリングを管理」

プレビュー後に確認する安全なワークフローで、自然言語によるファイアウォール管理を実現します。以下が含まれます。

• 一般的なシナリオ向けのポリシーテンプレート（references/policy-templates.yaml）：

  テンプレート	説明
  iot-isolation	IoT VLAN からメイン LAN へのアクセスをブロック
  guest-lockdown	ゲストネットワークをインターネットのみに制限
  kids-content-filter	DPI によるソーシャルメディアとゲームの時間帯別ブロック
  block-bittorrent	DPI による P2P／BitTorrent トラフィックのブロック
  work-vpn-split-tunnel	ローカル LAN へのアクセスを維持しながら、企業 VPN を許可
  camera-isolation	IP カメラとの通信を NVR のみに制限

• スナップショット／差分ワークフロー — Claude は、変更を行う前にすべてのポリシー、ゾーン、グループのタイムスタンプ付き JSON スナップショットを保存し、変更後の状態と比較することで、意図しない変更を即座に検出します。

• ファイアウォールスキーマ、DPI カテゴリー、テンプレートの全パラメーター一覧に関するリファレンスドキュメント

ファイアウォール監査ツール

トリガー：「ファイアウォールを監査」「ファイアウォールルールを確認」「セキュリティ上の問題をチェック」「ファイアウォールを採点」

4 つのカテゴリーにわたる 16 項目のセキュリティベンチマークを包括的に自動監査し、各検出事項の修正ガイダンスとともに 0～100 のスコアを算出します。Claude は MCP ツールの呼び出しを実行し、references/security-benchmarks.md に基づいて各ベンチマークを評価します。小規模な CLI（scripts/unifi-firewall-score）で検出事項を標準のバージョン安定スコアに変換するため、監査履歴を継続的に比較できます。

スコアのしきい値：

スコア	評価	意味
80–100	健全	軽微な不足はあるものの、ベストプラクティスに準拠しています
60–79	要対応	目立った不足があります。計画的なスケジュールに沿って対処してください
0–59	重大	早急な修正が必要な重大なリスクがあります

ベンチマークカテゴリー（4 × 25 点）：

• セグメンテーション（SEG-01–04）— IoT／ゲスト／管理 VLAN の分離、VLAN 間の明示的なポリシー
• 送信制御（EGR-01–03）— 高リスク VLAN の送信フィルタリング、DNS の適用、脅威インテリジェンスによるブロック
• ルールの衛生状態（HYG-01–05）— 競合、冗長／無効なルール、古い参照、命名、シャドーイング
• トポロジー（TOP-01–04）— オフラインデバイス、ファームウェアの最新性、スイッチのアップリンク間の VLAN の一貫性、孤立したポートプロファイル

各検出事項には、ベンチマーク ID、重大度（重大／警告／情報）、平易な説明が含まれます。また、自動修正が可能な場合は、修正するための正確な MCP ツール呼び出しも含まれます。監査履歴は audit-history.json に記録され、スコアの推移を経時的に確認できます。

---

ツールの改善

デバイスの分類（unifi_list_devices）

unifi_list_devices は、導入済みの各デバイスを正しく分類する device_category フィールドを返すようになりました。

カテゴリー	デバイス
ap	実際のアクセスポイント（ワイヤレスメッシュ経由で接続する USP Smart Power の電源タップを除く）
switch	管理対象スイッチ
gateway	セキュリティゲートウェイと Dream Machine
pdu	配電ユニット
wan	UCI ケーブルインターネットデバイス
unknown	識別できないデバイスタイプ

ap カテゴリーでは、デバイスタイプのプレフィックスだけでなく、コントローラーの is_access_point ブール値フラグを正式な判定基準として使用します。これにより、uap タイプのデバイスとして表示される USP Smart Power の電源タップは、AP カテゴリーから正しく除外されます。

拡充されたデバイスフィールド

各デバイスレコードには、既存の MAC、名前、モデル、IP、ファームウェア、稼働時間、ステータスに加えて、次のフィールドが含まれるようになりました。

フィールド	型	説明
device_category	string	意味的なカテゴリ：ap、switch、gateway、pdu、wan、unknown
upgradable	bool	ファームウェアのアップグレードが利用可能かどうか
connection_network	string	デバイスの管理インターフェイスが属する VLAN の名前
uplink	object	トポロジー情報：アップリンクの種類、速度、親デバイス名、ポート
load_avg_1	float	1 分間のロードアベレージ（デバイスのシステム統計情報から取得）
mem_pct	float	メモリ使用率（0～100）
model_eol	bool	デバイスモデルがサポート終了に達しているかどうか

---

ドキュメント

• 設定 — 環境変数の完全なリファレンス、YAML 設定、コントローラーの種類の検出
• 権限 — 権限システム、カテゴリごとのデフォルト設定、高リスクのツールを有効にする方法
• ツールカタログ — カテゴリ別に整理された 210 個のツール
• トランスポート — stdio、Streamable HTTP、SSE のセットアップ
• トラブルシューティングとサポートバンドル — レビュー済みのサポート証跡、接続の問題、SSL、不足しているツール

開発

cd apps/network
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