UniFi

UniFi MCP サーバー

Ubiquiti UniFi の Cloud Site Manager API 用 MCP サーバーです。サイト、ホスト、デバイス、WAN／ISP の健全性メトリクス、SD-WAN の設定／ステータスを、AI アシスタントおよび WYRE Conduit ゲートウェイ向けに提供します。

対象範囲：Cloud Site Manager API のみ（意図的な選択）

UniFi には、相互に異なる 2 種類の API があります。

• コントローラーごとのローカル API（Network Application API、developer.ui.com/network/...）：各顧客のコンソール／コントローラー上で動作します。サイトごとに個別の API キーが必要で、集中管理の統合ポイントはありません。また、クライアント、ネットワーク／VLAN／DHCP、WLAN／SSID、ファイアウォールルール、ポート転送など、サイトごとの設定を詳細に扱います。
• Cloud Site Manager API（developer.ui.com/site-manager/...、ベース URL は https://api.ui.com）：単一の UI.com アカウントキーで、そのアカウントに登録されたすべてのサイトのデータを集約します。ただし、読み取り可能な範囲はかなり限定的で、サイト、ホスト、デバイスインベントリ、WAN／ISP メトリクス、SD-WAN の設定／ステータスのみを公開します。

このコネクターの対象は Cloud Site Manager API のみです。これは上流で明示的に決定された範囲であり、コントローラーごとのローカル API は保留中で、代替手段としても実装されていません。

ツールの対応範囲に関する注意点： Cloud Site Manager API では、「一般的な」ネットワーク管理コネクターが備えていそうな機能のいくつかが公開されていません。クライアント一覧／詳細のエンドポイントはなく（サイトの statistics にクライアントの集計数が含まれるのみです）、VLAN／ネットワーク／DHCP 設定のエンドポイント、WLAN／SSID のエンドポイント、ファーストクラスの操作としてのファイアウォールルールのエンドポイントもありません。これらはすべて、コントローラーごとのローカル API でのみ利用できます。このコネクターは、Cloud Site Manager API の公開 OpenAPI 仕様で専用の読み取り操作として定義されている 10 個のパスのうち、9 個を実装しています。詳しくは、以下の「ツール」を参照してください。10 個目のパスはコネクタープロキシエンドポイントで、以下の専用サブセクションで説明します。これは実装漏れではなく、設計上対象外です。

認証

UniFi Site Manager は、UI.com アカウントに紐付けられた単一の静的な X-API-Key ヘッダーで認証します。OAuth フローも、トークン交換も、リクエストごとの有効期限もありません。unifi.ui.com の Settings > API Keys からキーを生成してください。

ここでは、確信度が意図的に異なる 2 つの主張を説明します。これらをひとまとめにして「読み取り専用」と述べないでください。

• 構造上の検証済み事項（直接確認済みで、確信を持って述べられる内容）： このコネクターのコードは変更を伴う呼び出しを一切行いません。client.ts 内のすべての関数は、以下に示す 9 個の専用読み取り操作のいずれかを呼び出します。src/ 内には POST／PUT／PATCH／DELETE の呼び出しはなく、コネクタープロキシのパス（以下を参照）も、どの名前でも参照されていません。
• ベンダーのドキュメントに記載されていますが、独自には検証されていません（意図的に断定を避けています）： Ubiquiti の Getting Started ドキュメントでは、Site Manager API キーは一般に読み取り専用であると説明されています（「現時点では読み取り専用であり、UniFi インフラストラクチャに変更を加えるためには使用できません」）。ただし、コネクタープロキシのパスに対して、この制限が実際にサーバー側で適用されているか、つまり UI.com のバックエンドが /v1/connector/consoles/{id}/*path 経由で送信された書き込み動詞を拒否するのか、それともこの制限が技術的な強制ではなく文書上の方針にとどまるのかは、WYRE ではテストしていません。このレビューで、実際の顧客インフラストラクチャに対する破壊的なテストを、同意なしに実行するべきではないという正しい判断のもと、誰も実際のキーを使って書き込み動詞を送信して確認していません。**このコネクターや README を、基盤となる API キーでは書き込みができないことを確認したものとして解釈しないでください。**確認できているのは、このコネクター自身のコードが書き込みを一切試みないことだけです。

ゲートウェイモードでは、キーはリクエストごとに X-UniFi-Api-Key ヘッダーを介して渡されます。ローカル／stdio モードでは、UNIFI_API_KEY から一度だけ読み込まれます。HTTP モードでは、署名付きの X-Gateway-S2S ヘッダーも必要です。詳しくは「設定」を参照してください。

コネクタプロキシエンドポイント（設計上、対象外）

現行の仕様（https://developer.ui.com/site-manager/v1.0.0/openapi.json。プレーンな curl／HTTP GET で直接取得しています。この特定の生の JSON エンドポイントは正常に応答しますが、developer.ui.com のインタラクティブなドキュメントページは、プレーンな fetch では表示されない JS SPA です）では、このコネクタが実装する 9 個に加えて、10 個目のパスとして /v1/connector/consoles/{id}/*path が定義されています。HTTP メソッドは 5 種類すべて（GET／POST／PUT／PATCH／DELETE）で、operationId は ConnectorGet／ConnectorPost／ConnectorPut／ConnectorPatch／ConnectorDelete です。これは汎用リバースプロキシであり、api.ui.com がリクエストをそのまま対象コンソールのローカル API（http://127.0.0.1/proxy/[path]）に転送します。これにより、コンソールの Network／Protect／InnerSpace のローカル API 全体にアクセスできます。このコネクタの Scope セクションで対象外としている、コントローラーごとの同じローカル API に、コンソールへ直接アクセスする代わりにクラウドエンドポイント経由でアクセスする仕組みです。仕様では、実際に変更を加える機能として記載されています。たとえば、DELETE の例ではホットスポットのバウチャーを削除します。また、標準（非組織）API キーでも利用でき、そのキーの所有者が管理するコンソールが対象です。組織向けのキーが必須というわけではありません。（WYRE はこのパスに対する実際の書き込みリクエストを送信していません。上記「認証」に記載の留保を参照してください。）

このコネクタでは、ローカルのコントローラーごとの API を対象外としているのと同じ理由で、コネクタプロキシエンドポイント全体を意図的に除外しています。これを実装すると、ワイルドカードのパススルーツール 1 つを介して、クライアント、VLAN、WLAN、ファイアウォールルール、実際の変更操作など、ローカル API 全体を再公開することになり、このコネクタを目的に特化したクラウド読み取り機能に限定する意図が損なわれるためです。このコネクタ内のツールは、どのような名前であっても、このエンドポイントを呼び出しません。

設定

.env.example をコピーし、以下の変数を設定してください。

環境変数	必須	説明
UNIFI_API_KEY	stdio および AUTH_MODE=env の場合	UniFi Cloud Site Manager API キー（X-API-Key）。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http。
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose）または env。Gateway モードでは、各 /mcp リクエストに X-UniFi-Api-Key が必要であり、UNIFI_API_KEY にはフォールバックしません。env は S2S 認証の成功後にのみ、この変数を使用します。未設定の場合は env になります（stdio およびシングルテナント HTTP）。
CONDUIT_S2S_SECRET	HTTP の場合は必須	サービス間シークレット。この値が空、または既知のプレースホルダー（changeme、secret、replace-me、your-s2s-secret、その他の例示値）の場合、HTTP サーバーはエラーをログに記録し、ゼロ以外の終了コードで終了します。openssl rand -hex 32 で生成してください。Compose はこの値がないと起動しません。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	ローカル開発で CONDUIT_S2S_SECRET なしに HTTP を起動する場合に限り、正確に 1 を設定してください。プロセスは警告をログに記録し、X-Gateway-S2S を強制せず、127.0.0.1 のみでバインドします。ループバック以外の MCP_HTTP_HOST は上書きされ、その旨がログに記録されます。既知のプレースホルダーシークレットが設定されている場合は、引き続き起動を拒否します。
MCP_HTTP_HOST	いいえ	有効な CONDUIT_S2S_SECRET が設定されている場合のバインドアドレス。未設定の場合は、従来どおり 0.0.0.0 でバインドします。イメージと Compose では、コンテナ内で 0.0.0.0 を設定します。シークレットがない場合は、この値にかかわらずリスナーは 127.0.0.1 になります。
MCP_HTTP_PORT	いいえ	HTTP ポート。デフォルトは 8080 です。
LOG_LEVEL	いいえ	debug | info（デフォルト）| warn | error。

/health と /healthz は認証なしで利用でき、認証情報も読み取りません。stdio トランスポートは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http と CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。検証処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> 形式で、CONDUIT_S2S_SECRET をキーとするリテラル文字列 t=<unix seconds> の HMAC-SHA256 を表す 64 文字の小文字の 16 進数です。タイムスタンプはサーバーの時計との誤差が 300 秒以内でなければなりません。ヘッダーがない、または無効な場合は、UniFi API キーを読み取る前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-UniFi-Api-Key: $UNIFI_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-UniFi-Api-Key も必要です。このリクエストの認証情報は、このヘッダーのみが使用されます。AUTH_MODE=env の場合も署名付きの X-Gateway-S2S ヘッダーが必要で、その後、環境変数の UNIFI_API_KEY が使用されます。

ツール

読み取り専用ツールは 9 個です。Cloud Site Manager API の公開仕様における、専用の読み取り操作ごとに 1 個ずつあります（公開仕様には合計 10 個のパスがあります。10 個目の汎用変更用コネクタプロキシエンドポイントは、設計上除外されています。上記の「認証」を参照してください）。

サイト

• unifi_list_sites - この API キーのアカウントから参照できるすべてのサイトを、メタデータ（名前、タイムゾーン、ゲートウェイ MAC アドレス）と集計統計（デバイス数／クライアント数、ネットワークパフォーマンス）とともに一覧表示します。

ホスト

• unifi_list_hosts - この API キーのアカウントに関連付けられたすべてのホスト（コンソール／ネットワークサーバーアプリケーション）を一覧表示します。
• unifi_get_host - ID を指定して、単一のホストの詳細情報を取得します。

デバイス

• unifi_list_devices - このアカウントが所有またはスーパー管理者権限を持つホストが管理する UniFi デバイスを、ホストごとにグループ化して一覧表示します。PII を含みます（デバイスごとの MAC アドレス、IP アドレス、ユーザー定義のホスト名／メモ）。デフォルトでは管理者権限が必要です。

WAN／ISP の健全性

• unifi_get_isp_metrics - リンクされているすべてのサイトの WAN／ISP の健全性とトラフィック指標を、5 分または 1 時間単位で取得します。
• unifi_query_isp_metrics - 同じ指標を、指定したホスト／サイトの組み合わせと期間に絞って取得します。UniFi API への POST ですが、フィルタリングされた読み取りであり、変更操作ではありません。

SD-WAN

• unifi_list_sdwan_configs - すべての SD-WAN 設定を一覧表示します（ID／名前／タイプのみ）。
• unifi_get_sdwan_config - 1 つの SD-WAN 設定の完全なトポロジー（ハブ／スポークのサイト、接続されたネットワーク、ルーティング対象のサブネット（CIDR））を取得します。ネットワークトポロジーのデータです。デフォルトでは管理者権限が必要です。
• unifi_get_sdwan_config_status - 1 つの SD-WAN 設定のデプロイ状況を取得します。ハブ／スポークごとの WAN IP とレイテンシーも含まれます。ネットワークトポロジーのデータです。デフォルトでは管理者権限が必要です。

unifi_list_sites、unifi_list_hosts、unifi_get_host、unifi_get_isp_metrics、unifi_query_isp_metrics、unifi_list_sdwan_configs は通常の読み取りティアです。サイト／ホストは、ほかの多くのツールで必要となるサイト／ホスト ID を調べるためのナビゲーション用ディレクトリです。また、WAN 指標は集計されたパフォーマンスデータであり、PII やトポロジー情報ではありません。

機密性

このコネクターの 9 個のツールはすべて読み取り専用ですが、機密データを 2 種類扱います。PII（unifi_list_devices が返すすべてのデバイスの MAC アドレス、IP アドレス、ユーザー定義のホスト名）と、ネットワークトポロジー（unifi_get_sdwan_config／unifi_get_sdwan_config_status の SD-WAN ハブ／スポークのルートとサブネット）です。Conduit の配線設定では、この 3 つのツールはデフォルトで isAdmin: true に設定され、それ以外はすべて通常の読み取りです。これは「認証」で説明したコネクタプロキシエンドポイントとは別の扱いであり、そのエンドポイントはここでは一切実装されていないため、このコネクターのティアモデルには含まれません。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

イメージはコンテナ内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、デフォルトで AUTH_MODE=gateway になります。ポートをループバックに公開し、実際の S2S シークレットを渡してください。ゲートウェイモードでは、UniFi API キーは各リクエストの X-UniFi-Api-Key として渡され、環境変数からは読み込まれません。

docker build -t unifi-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  unifi-mcp

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。ゲートウェイサービスは AUTH_MODE=gateway を設定し、UNIFI_API_KEY を注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、その後 UNIFI_API_KEY を使用します。これは上記のゲートウェイ Compose サービスとは別の構成です。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e UNIFI_API_KEY=your-value \
  -p 127.0.0.1:8080:8080 \
  unifi-mcp

シークレットなしのローカル HTTP は、開発用途に限られます。127.0.0.1 にバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は上書きされます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

ライセンス

Apache-2.0