unifi

UniFi MCP サーバー

公式 Site Manager API と Cloud Connector を基盤とし、他の UniFi MCP にはないサイト横断分析を備えた、MSP スタイルの UniFi MCP です。

セマンティック分析の集約ツール7個、Site Manager の生データ取得ツール9個、Cloud Connector ツール35個の計54個に加え、Cloud API では取得できないポートごとのエラーカウンターと SFP DDM を取得する、オプションのローカルコントローラーツールを2個備えています。厳選したしきい値に基づく重大度判定（healthy／info／warning／critical）を提供します。MCP プロンプトは8個（フリート全体の運用向け4個＋MSP ワークフロー向け4個）です。読み取り専用です。Ubiquiti の API キーでは、まだ書き込み操作はサポートされていません。

起動前診断

npx -y @us-all/unifi-mcp --doctor

環境変数を検証し、Site Manager API に ping を送信し、Cloud Connector を確認（オーナーキーが設定されている場合）してから、カテゴリーの有効・無効設定をチェックします。重大な問題がある場合はゼロ以外の終了コードで終了するため、CI やデプロイ前スクリプトで使用できます。

他にはない機能

• Site Manager の分析 — site-health-timeline、summarize-site、firmware-inventory、compare-sites、wan-uptime-trend、top-clients-by-bandwidth、list-sites-overview。これらを公開している UniFi MCP は他にありません。
• 数値だけでなく、重大度を判定 — すべての分析ツールが、厳選した理由とともに healthy / info / warning / critical / unknown を返します。しきい値も厳選しており（例：WAN 稼働率 <90% は critical、再起動後の startupTime <1h は critical）、用途に応じて設定されています。
• Cloud Connector を標準機能として提供 — 公式の /v1/connector/consoles/{id}/... プロキシを通じた35個のツールを備えています。connectorAvailable（機能の利用可否）と connectorResolved（今回の呼び出しで解決済みか）を分けています。
• 集約ツール — 連続する3～7回の呼び出しを1回にまとめ、部分的な失敗を示す caveats 配列を返します（例：Site Manager API では WAN 稼働率を期間指定で取得できないことを明示します）。
• MCP プロンプト（8個）— フリート運用向け：triage-site-degradation、firmware-rollout-audit、wan-uptime-report、cross-site-anomaly-detection。MSP ワークフロー向け：msp-onboard-site-checklist、msp-monthly-client-report、msp-fleet-firmware-plan、msp-bandwidth-complaint-investigation。
• トークン効率を重視した設計 — @us-all/* MCP の中で最小のスキーマフットプリントを実現しています（オーナーキーを設定した場合、デフォルトで約5Kトークン）。200台を超えるデバイスのフリートも、単一のセッション内で分析できます。
• Apps SDK カード — ChatGPT クライアントでは、_meta["openai/outputTemplate"] を使って summarize-site をフリートのステータスカード（オンライン率、WAN 稼働率、ゲートウェイ、デバイス）として表示します。Claude クライアントには、同じ JSON コンテンツを返します。
• stdio と Streamable HTTP — デフォルトは stdio です。ChatGPT Apps SDK またはリモートクライアントで使用するには、MCP_TRANSPORT=http を設定します（MCP_HTTP_TOKEN による Bearer 認証）。
• ローカルコントローラーへの直接アクセス（v1.13.0）— UNIFI_LOCAL_* 環境変数をオプトインで設定すると、Cloud Connector を経由せず、LAN 上でコントローラーの旧式 /api/s/{site}/stat/device/{mac} に直接アクセスする2個のツールが有効になります。get-port-errors（ポートごとの rx/tx エラー、リンクフラップカウンター、SFP DDM — Rx/Tx 電力 dBm、温度、電圧、TX/RX 障害）と list-port-flap-summary（フリート全体のポート不安定度ランキング）を利用できます。Integration API では取得できないデータを提供します。LAN から到達可能である必要があります。

お試し用プロンプト — 5 例

サーバーを Claude Desktop または Claude Code に接続し、次のいずれかを貼り付けてください。

1. MSP の朝のチェック — 「すべての UniFi サイトでフリートの健全性を確認してください。healthy ではないものを重大度と上位 3 件の問題とともに抽出してください。」
2. ファームウェア展開の監査 — 「すべてのサイトで古いファームウェアを使用しているデバイスを見つけてください。サイトごとにまとめ、現在のバージョンと最新バージョンを示し、重要度の高い順にしてください。」
3. サイトの劣化状況のトリアージ — 「USM サイトで WiFi に関する苦情があります。過去 24 時間分のデバイスのステータス、WAN の稼働時間、最近の再起動、帯域幅使用量の多いクライアントを取得してください。異常な点はありますか？」
4. WAN SLA レポート — 「すべてのサイトについて、月次 WAN 稼働時間レポートを作成してください。5 分を超える停止、デュアル WAN のフェイルオーバーイベント、目標値 99.5% を下回るサイトを明らかにしてください。」
5. サイト間の異常検知 — 「USS を他のサイトと比較してください。AP ごとのクライアント数、トラフィックパターン、デバイスのファームウェア構成を比較し、外れ値を抽出して、最も可能性の高い原因を提案してください。」
6. ポートのリンク断続のトリアージ（UNIFI_LOCAL_* が必要） — 「すべてのスイッチの全ポートを、不安定度スコア順に並べてください。最も問題の多い上位 3 ポートについて、利用可能であれば SFP DDM を取得し、信号自体に問題があるのか、それとも下流に原因があるのかを教えてください。」

他の UniFi MCP と使い分ける場合

	sirkirby/unifi-mcp	enuno/unifi-mcp-server	@us-all/unifi-mcp（本サーバー）
GitHub スター数	291	117	—
ツール数	224	74	54
対象範囲	Network + Protect + Access + Drive	Network + マルチサイト + QoS + バックアップ	Site Manager + Cloud Connector + 分析
Site Manager API	❌	部分対応	✅ 詳細対応 + 分析
Cloud Connector	❌	部分対応（3 モード）	✅ 利用可能／解決済みを分離
UniFi Protect（カメラ）	✅	❌	❌（対象外）
UniFi Access（ドア）	✅	❌	❌（対象外）
集約ツール	❌	❌	✅ 7
重大度の判定	❌	❌	✅ 厳選したしきい値
MCP プロンプト	❌	❌	✅ 8（MSP ワークフロー 4 件を含む）

カメラ（Protect）やドアアクセスが必要な場合は、sirkirby を使ってください。Network API の生の機能を幅広く使いたい場合は、enuno を使ってください。MSP スタイルのマルチサイト分析、フリートのトリアージ、多数のコンソールにまたがる「何かおかしい点はあるか？」という質問には、本サーバーを使ってください。

インストール

Claude Desktop

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "@us-all/unifi-mcp"],
      "env": {
        "UNIFI_API_KEY": "<your-key>",
        "UNIFI_API_KEY_OWNER": "<owner-key-or-same-key-if-role=owner>"
      }
    }
  }
}

Claude Code

claude mcp add unifi -s user \
  -e UNIFI_API_KEY=<your-key> \
  -e UNIFI_API_KEY_OWNER=<owner-key> \
  -- npx -y @us-all/unifi-mcp

ソースからビルド

git clone https://github.com/us-all/unifi-mcp-server.git
cd unifi-mcp-server && pnpm install && pnpm build
node dist/index.js

API キー — 種類と取得場所

導入時に最もよくあるつまずきです。UniFi には、同じ https://api.ui.com/v1 を通じて利用する 2 つのサーフェスがあります。

サーフェス	提供内容	パス	環境変数
Site Manager	ホスト、サイト、デバイスの概要、ISP メトリクス、SD-WAN 設定（集約済み、コンソール全体）	/v1/hosts、/v1/sites、/v1/devices、/v1/sd-wan-configs	UNIFI_API_KEY
Cloud Connector	デバイスごとの情報、クライアントごとの情報、ネットワーク、ファイアウォール、WiFi（ローカルコントローラーへのプロキシ）	/v1/connector/consoles/{hostId}/...	UNIFI_API_KEY_OWNER

API キーの権限は、そのキーを作成したアカウントのロールを引き継ぎます。

アカウントのロール	Site Manager	Cloud Connector
管理者（オーナー以外）	✅	❌ 403
オーナー	✅	✅

オーナーロールを持っている場合は、両方の環境変数に同じキーを設定してください。 これは @us-all の利用者に最もよくあるケースです。

キーを取得するには、unifi.ui.com → Settings → API → Generate に進みます。GA で現在選択できるのは View Only のみです（Full Access はグレー表示 — 書き込みには Early Access プログラムへの参加が必要です）。

Cloud Connector の要件

• コンソールのファームウェアが 5.0.3 以上
• API パス：https://api.ui.com/v1/connector/consoles/{hostId}/{appPath}
• ローカルの siteId は UUID であり、リテラル文字列 default ではありません
• 利用可能なエンドポイント：Network integration API（/network/integration/v1/sites、devices、clients、networks）。旧パス（/api/s/{site}/stat/event）は 404 を返します。イベントログ／syslog は公開されていません。

ローカルコントローラー（任意、v1.13.0+）

Cloud Connector が対応していない、ポートごとのエラーカウンター、フラップカウンター、SFP DDM を補う 2 つのツールを追加します。これらの情報は /api/s/{site}/stat/device/{mac}（レガシー）にありますが、公式の Network Integration API では公開されていません（OpenAPI 仕様 v10.4.57 で確認済み）。

要件：

• この MCP を実行するホストからコントローラーへの LAN/VPN 接続（通常は https://<controller-ip>）
• コントローラーのローカルアカウント（Viewer / Limited Admin ロールで十分です。Owner の認証情報は不要です）
• 自己署名証明書の処理：標準の UDM Pro では UNIFI_LOCAL_INSECURE=true を設定します

認証フロー：POST /api/auth/login（Cookie）→ 以降のすべての呼び出しでセッションを再利用します。401 が返された場合は自動的に再ログインします。読み取り専用です。

設定

変数	必須	デフォルト	説明
UNIFI_API_KEY	✅	—	unifi.ui.com の API キー（任意の管理者ロール）
UNIFI_API_KEY_OWNER	❌	—	Owner ロールの API キー — Cloud Connector ツール 35 個を有効にします。キーが Owner ロールの場合は、同じ値を設定してください。
UNIFI_API_URL	❌	https://api.ui.com/v1	API ベース URL
UNIFI_TOOLS	❌	—	カテゴリのカンマ区切り許可リスト。
UNIFI_DISABLE	❌	—	カンマ区切りの拒否リスト。UNIFI_TOOLS が設定されている場合は無視されます。
MCP_TRANSPORT	❌	stdio	Streamable HTTP トランスポートを有効にするには http を指定します
MCP_HTTP_TOKEN	条件付き	—	Bearer トークン。MCP_TRANSPORT=http の場合は必須です
MCP_HTTP_PORT	❌	3000	HTTP リッスンポート
MCP_HTTP_HOST	❌	127.0.0.1	HTTP バインドホスト（localhost では DNS リバインディング保護が自動的に有効になります）
MCP_HTTP_SKIP_AUTH	❌	false	Bearer 認証を省略します。処理を担うリバースプロキシの背後に配置する場合などに使用します
UNIFI_LOCAL_URL	❌	—	ローカルコントローラーの URL（例：https://10.10.1.1）。これに USER/PASS を設定すると、local カテゴリのツール 2 個が有効になります。
UNIFI_LOCAL_USER	条件付き	—	コントローラーのローカルアカウントのユーザー名（UNIFI_LOCAL_URL の設定時に必須）。Viewer/Limited-Admin ロールで十分です。
UNIFI_LOCAL_PASS	条件付き	—	コントローラーのローカルアカウントのパスワード（UNIFI_LOCAL_URL の設定時に必須）。
UNIFI_LOCAL_SITE	❌	default	レガシー /api/s/{site}/* のサイトスラッグ。
UNIFI_LOCAL_INSECURE	❌	false	自己署名証明書を許可します（UDM Pro では一般的です）。

カテゴリ（9 個）：analysis、raw、devices、clients、networks、firewall、wan、reference、local。

MCP_TRANSPORT=http の場合：POST /mcp（Bearer 認証付き JSON-RPC）+ GET /health（認証不要の稼働確認）。

トークン効率

@us-all/* MCP の中で、スキーマのフットプリントが最も小さい構成です。

シナリオ	ツール	スキーマトークン数
デフォルト（Owner なし）	17	1,700
UNIFI_TOOLS=analysis	8	1,000（−42%）
Owner キーあり（デフォルト）	52	約 5,000
UNIFI_TOOLS=analysis + Owner	8	1,000（−80%）

重大度としきい値

各分析ツールは、次のいずれかを返します。

• healthy — 問題なし
• info — 情報提供のみ。対応不要
• warning — 注意が必要
• critical — 直ちに対応が必要
• unknown — API エラーまたはデータ不足

設定済みのしきい値：

条件	重大度
デバイスがオフライン	critical
startupTime < 1h	critical（再起動直後）
startupTime < 24h	warning（最近の再起動）
startupTime < 72h	info（監視）
WAN 稼働率 < 90%	critical
WAN 稼働率 < 95%	warning

MCP プロンプト（8）

MCP prompts/list で利用できるワークフローテンプレートです。4 つはフリート運用向け、4 つは MSP（マネージドサービスプロバイダー）固有のワークフローです。

フリート運用：

• triage-site-degradation — サイトからの苦情に対処するワークフローです。デバイス、WAN、再起動、クライアントの順に確認します。
• firmware-rollout-audit — フリート全体のファームウェア差分と、ロールアウトの安全性を確認します。
• wan-uptime-report — 複数サイトにわたる月次の WAN SLA 形式レポートです。
• cross-site-anomaly-detection — サイトをフリートの基準値と比較し、外れ値を検出します。

MSP ワークフロー：

• msp-onboard-site-checklist — 新たに追加された顧客サイトの合否判定チェックリストです（ファームウェアの最低バージョン、コンソール接続、稼働時間の傾向、コネクターの利用可否、ファイアウォールの健全性、最近の再起動、保留中のデバイス）。
• msp-monthly-client-report — 顧客向けの月次健全性レポートです（1 サイトについて、概要、ネットワークの可用性、デバイス、上位ユーザー、推奨事項を、専門知識がなくても理解できる表現でまとめます）。
• msp-fleet-firmware-plan — リスク許容度に応じて順序付けた、目標ファームウェアバージョンへの段階的な N 波ロールアウト計画です。メンテナンス時間帯とロールバックのトリガーを含みます。
• msp-bandwidth-complaint-investigation — WAN の傾向、ISP 指標、上位クライアント、DPI カテゴリー、最近の再起動を確認し、「サイト X のインターネットが遅い」という苦情を調査します。

MCP リソース

• unifi://site/{hostName}/devices — サイトのデバイスのスナップショット
• unifi://reboots/recent — フリート全体で最近再起動したデバイス

ツール（54 + オプションのローカルツール 2 個）

9 カテゴリーあります。実行時にツールを検索するには search-tools を使用します。全リストは以下に折りたたまれています。Cloud Connector ツール（33 個）は UNIFI_API_KEY_OWNER が設定されている場合にのみ登録されます。設定されていない場合、利用できるのは 19 個です。ローカルコントローラーのツール（2 個）は UNIFI_LOCAL_URL/USER/PASS が設定されている場合にのみ登録されます。

グループ	ツール数
セマンティック分析（集計を含む）	9
Site Manager の生データ	9
Cloud Connector（デバイス／クライアント／ネットワーク／WiFi／ファイアウォール／WAN／リファレンス）	33
ローカルサイト（list-local-sites、get-app-info）	2
ローカルコントローラー（get-port-errors、list-port-flap-summary）	2
メタ（search-tools）	1

ツールの全リスト

セマンティック分析（9）

list-sites-overview、analyze-site-health、detect-recent-reboots、compare-sites、firmware-inventory、wan-uptime-trend、top-clients-by-bandwidth、summarize-site (集計)、site-health-timeline (集計)

Site Manager API（9）

list-hosts、get-host、list-sites、list-devices、get-isp-metrics（オプション）、query-isp-metrics（オプション）、list-sdwan-configs、get-sdwan-config、get-sdwan-config-status

Cloud Connector — デバイス（4）

get-device-details、get-device-by-id、get-device-statistics、list-pending-devices

Cloud Connector — クライアント（2）

list-site-clients、get-client-details

Cloud Connector — ネットワーク（3）

list-networks、get-network-details、get-network-references

Cloud Connector — WiFi（2）

list-wifi-broadcasts、get-wifi-broadcast-details

Cloud Connector — ファイアウォール／ACL／DNS（10）

list-firewall-zones、get-firewall-zone、list-firewall-policies、get-firewall-policy、get-firewall-policy-ordering、list-acl-rules、get-acl-rule、get-acl-rule-ordering、list-dns-policies、get-dns-policy

Cloud Connector — トラフィック／WAN／VPN（5）

list-traffic-matching-lists、get-traffic-matching-list、list-wans、list-vpn-tunnels、list-vpn-servers

Cloud Connector — ホットスポット／リファレンス（7）

list-vouchers、get-voucher-details、list-radius-profiles、list-device-tags、list-dpi-categories、list-dpi-applications、list-countries

ローカルサイト（2）

list-local-sites、get-app-info

### ローカルコントローラー（2、`UNIFI_LOCAL_*` でオプトイン） - `get-port-errors` — ポートごとの `rx_errors` / `tx_errors` / `rx_dropped` / `tx_dropped` とリンク状態に加え、永続的なフラップカウンター（`linkDownCount`、`stpChangeCount`、`anomalies`）を取得します。トランシーバーが接続されている場合は **SFP DDM**（`rxPowerDbm`、`txPowerDbm`、`temperatureC`、`voltageV`、`txBiasMa`、`rxFault`、`txFault`、ベンダー／部品番号／シリアル番号）も取得します。トリアージ用の `onlyProblems` フィルターを利用できます。 - `list-port-flap-summary` — コントローラー内のすべてのスイッチを反復処理し、スコア `linkDownCount*2 + stpChangeCount + rx_errors + tx_errors` に基づいてサイト全体のポートを順位付けします。サイト内の不安定なケーブル／トランシーバー／NIC の省電力機能が有効なエンドポイントをまとめて表示します。カウンターはクエリ間で保持されます（スイッチの再起動時のみリセット）。

メタ

search-tools — キーワードでほかのツールを検索します。常に有効です。

アーキテクチャ

Claude → MCP stdio → src/index.ts
                      ├── tools/analysis.ts     → Site Manager API (UNIFI_API_KEY)
                      ├── tools/*.ts (raw)       → Site Manager API (UNIFI_API_KEY)
                      ├── tools/connector.ts     → Cloud Connector  (UNIFI_API_KEY_OWNER)
                      └── tools/local-ports.ts   → Local Controller (UNIFI_LOCAL_URL + LAN)
                      helpers/resolver.ts        → hostName ↔ ID mapping

@us-all/mcp-toolkit を基盤としています。

• extractFields — トークン効率の高いレスポンス投影
• aggregate(fetchers, caveats) — summarize-site / site-health-timeline 用のファンアウトヘルパー
• createWrapToolHandler — X-API-KEY の秘匿化と ConnectorError / UniFiError の抽出
• リトライ：最大3回、指数バックオフ（1秒 → 2秒 → 4秒）＋ジッター、Cloud Connector のタイムアウトは30秒

制限事項

• 読み取り専用 — UniFi API キーではまだ書き込みをサポートしていません（GA では Full Access ロールがグレーアウトされています）。
• レート制限 — 安定版 v1 では10,000リクエスト／分、Early Access では100リクエスト／分です。
• Cloud Connector の部分的なプロキシ — Network 統合 API は動作しますが、レガシーパスは404を返します。イベントログ／syslog は公開されていません。
• ISP Metrics — アカウント／プランによっては404が返される場合があります。

技術スタック

Node.js 22+ • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • zod v4 • dotenv。

ライセンス

MIT