UISP

UISP MCP サーバー

Ubiquiti UISP の REST API（/nms/api/v2.1）向けの MCP サーバーです。UISP ネットワーク／ISP 管理インスタンス全体のサイト、デバイス、障害（アラート機能）、イベント／監査ログ、データリンク、ゲートウェイ、バックグラウンドタスク、利用可能なファームウェア、速度テストを、AI アシスタントおよび WYRE Conduit ゲートウェイで利用できます。

認証

UISP は、UISP コンソールの Settings -> Users -> API tokens で生成する静的なアカウントトークンで認証します（トークンは読み取り専用または読み書きモードで発行できます。このコネクターには読み取り専用トークンを発行してください）。UISP には複数テナントで共有されるエンドポイントはありません。Ubiquiti のホスト型クラウド階層も含め、各デプロイメントはそれぞれ固有のインスタンス FQDN で稼働するため、このコネクターにはトークンとベース URL の両方が必要です。トークンは <base URL>/nms/api/v2.1/... へのリクエストで x-auth-token ヘッダーとして送信されます。ゲートウェイモードでは、どちらもリクエストごとに X-UISP-Api-Key および X-UISP-Base-URL ヘッダー経由で渡されます。ローカル／stdio モードでは、UISP_API_KEY と UISP_BASE_URL から一度読み込まれます。

認証情報のスコープ

ベンダーのドキュメントに基づく情報であり、稼働中のインスタンスに対する独立した検証は行っていません（「検証」を参照）：UISP のコンソールでは、トークンの作成時に「Read Only」または「Read/Write」モードを指定できます。これは、このコネクターに渡す前に読み取り専用にスコープを限定するための、ベンダーが正式にサポートする方法です。フリート内の一部のベンダーでは、キーが作成者の全権限を常に引き継ぐため、それらとは異なります。このコネクターのコードが発行するのは GET リクエストのみですが（「スコープ」を参照）、「書き込み不可」の適用はこのコネクターではなく UISP が行います。読み取り専用トークンを発行することが顧客側の保証であり、このコネクターが外部から強制できるものではありません。

関連して明記しておくべき点があります。UISP はネットワーク管理プラットフォームであると同時に、軽量な ISP CRM（UCRM）でもあります。この API の Site には実際の顧客名を含むリンク済みの ucrm.client 参照が含まれる場合があり、uisp_list_site_clients は顧客レコードを返します。このため、いくつかのツールは、単なるインフラのインベントリー情報を扱うように見える場合でも、isAdmin: true に分類されています。詳細な説明は「スコープ」および Conduit の vendor-config.ts にあるこのコネクターのエントリーを参照してください。

検証

このコネクターは、UISP 独自の生成済み OpenAPI／Swagger 仕様（タイトル UISP API、swagger: "2.0"、basePath: /nms/api/v2.1、securityDefinitions.UserSecurity = x-auth-token ヘッダー）に直接基づいて構築されています。UISP のすべてのインストール環境では https://<instance>/nms/api-docs/ に Swagger UI が公開されており、このコネクターのツールは、二次資料や命名規則ではなく、その仕様に記載された 180 件の GET 操作と一つずつ照合して検証されています。ただし、稼働中の UISP インスタンスに対する独立した検証は行っていません。UISP は ISP ごとにデプロイされ（セルフホスト、または Ubiquiti のホスト型クラウド階層を利用するには、有効な ISP／ネットワーク事業者アカウントが必要です）、このビルド環境では実際のトークンを使った一連の動作を試せるインスタンスがありませんでした。これはビルド環境の制約であり、ベンダー側の承認ゲートによるものではありません。ホスト型クラウド階層では、ISP 事業者が実際にセルフサービスでサインアップできます。

設定

環境変数	説明
UISP_API_KEY	UISP コンソールで発行するアカウントトークンです。
UISP_BASE_URL	UISP インスタンスのベース URL です（例：https://uisp.example.com）。
MCP_TRANSPORT	stdio（デフォルト）または http です。
AUTH_MODE	env（デフォルト。上記の変数を読み込みます）または gateway（Conduit ゲートウェイが挿入する X-UISP-Api-Key／X-UISP-Base-URL ヘッダー経由で、認証情報をリクエストごとに受け取ります）。
CONDUIT_S2S_SECRET	設定すると、HTTP トランスポートはすべての /mcp リクエストで有効な X-Gateway-S2S ヘッダー（Conduit サイドカー認証）を要求します。
LOG_LEVEL	debug | info（デフォルト）| warn | error です。

リクエスト制限

• HTTP リクエストボディの上限は 256 KiB（262144 bytes）です。X-Gateway-S2S のチェックに合格した後、Content-Length が上限を超えている場合は、JSON-RPC エラーとともに 413 が返されます。Content-Length のないボディには、MCP SDK のトランスポートによる上限が適用されます。認証されていないリクエストには、先に 401 が返されます。
• tools/call の引数は 10,000 要素（あらゆる深さにある配列の各項目とオブジェクトの各キー）までに制限されています。これを超える入力は isError のツール結果を返し、ディスパッチされません。

これらの制限は、CVE-2026-111768 / GHSA-46jr-4wx8-v453（検証中のメモリ枯渇）と GHSA-f897-62hf-6gxq（リクエストボディ／バッチの上限がない問題）に対処するものです。

ツール

サイト

• uisp_list_sites - サイト（ネットワーク上の拠点であるサイト、エンドポイント、クライアント。各項目は任意で UCRM のクライアント／サービスレコードに紐付け可能）を一覧表示します。
• uisp_get_site - 単一サイトの詳細を取得します。
• uisp_search_sites - 名前、住所、MAC アドレス、IP アドレスでサイト／エンドポイント／クライアントを検索します。
• uisp_list_site_clients - 指定した（親）サイトに属するすべてのクライアントサイトを一覧表示します。
• uisp_get_site_statistics - サイトと親サイト間のアップロード／ダウンロードトラフィックを取得します。
• uisp_get_site_traffic_summary - 指定した期間について、現時点までのサイトの合計アップロード／ダウンロード量を取得します。

デバイス

• uisp_list_devices - デバイス（ホスト名／IP／MAC、ステータス、親サイト）を一覧表示します。
• uisp_get_device - 単一デバイスのステータス概要を取得します。
• uisp_get_device_detail - デバイスの詳細を取得します。インターフェイスや接続中のステーションを含めるかどうかは任意です。
• uisp_get_device_statistics - デバイスのテレメトリ（CPU／RAM／信号／温度／スループット）を取得します。
• uisp_list_device_interfaces - 設定済み IP アドレスを含む、デバイスのネットワークインターフェイスを一覧表示します。
• uisp_get_device_by_mac - MAC アドレスでデバイスを検索します。
• uisp_list_discovered_devices - ネットワーク上で検出されたものの、まだ追加されていないデバイスを一覧表示します。

障害

• uisp_list_outages - ネットワーク障害（UISP のアラート機能）を一覧表示します。デバイス、種類、進行中かどうかで絞り込めます。

ログ

• uisp_list_logs - UISP のイベント／監査ログ（ログイン、デバイスの状態変更、バックアップ、アップグレード）を一覧表示します。

データリンク

• uisp_list_data_links - データリンク（UISP がデバイスとサイト間にマッピングした無線／有線リンク）を一覧表示します。
• uisp_get_data_link - 単一のデータリンクの詳細を取得します。
• uisp_list_site_data_links - 指定したサイトに紐付くデータリンクを一覧表示します。

ゲートウェイ

• uisp_list_gateways - ゲートウェイ（ネットワークゲートウェイとして設定されたルーター）と、その NetFlow／QoS／停止設定を一覧表示します。
• uisp_get_gateway - 単一ゲートウェイの詳細を取得します。

タスク

• uisp_list_tasks - バックグラウンドタスク（ファームウェアのアップグレード、バックアップ、一括操作）とそのステータスを一覧表示します。
• uisp_get_tasks_in_progress - 現在進行中のタスク数を取得します。

ファームウェア

• uisp_list_firmwares - UISP がサポートするデバイスモデルで利用可能なファームウェアバージョンを取得します。

速度テスト

• uisp_get_speed_tests - 実行中および最近の速度テストの詳細を取得します。

システム

• uisp_get_version - UISP のバージョン、デプロイタイプ、ビルド情報を取得します。認証情報や接続状態の確認に役立ちます。
• uisp_get_network_statistics - ネットワーク全体の統計（クライアント／サイト数、ネットワークの健全性、信号／リンク／ISP スコア、障害数）を取得します。
• uisp_get_summary - インスタンス全体のバッジ件数に相当する値（未読ログ／障害／ファームウェア、アクティブなクライアント／サイト数）を取得します。

スコープ

これは、サイトとデバイスのインベントリ、ステータス、テレメトリー、障害、および監査ログに限定した、意図的に範囲を絞った読み取り専用の v1 インターフェースです。それ以外は一切対象にしていません。 UISP 自身の OpenAPI 仕様には、はるかに広範な範囲にわたる 325 個のパス（うち 180 個は GET）が記載されています。これには、ネットワークとデバイスの完全な設定およびプロビジョニング、CRM／請求、ユーザーと API トークンの管理、デバイス認証情報の保管、バックアップ、サーバー管理、計画／シミュレーションツールが含まれます。このコネクターは、その仕様から 27 個の GET 操作を一つずつ検証して実装し、それ以外は見落としではなく設計上の判断で除外しています。

完全に除外（デバイス認証情報の保管庫）—実装していません： GET /vault/credentials、/vault/credentials/devices、/vault/{deviceId}/credentials。これは文字どおりデバイスのログイン認証情報を保管する場所であるため、HTTP メソッドにかかわらず全面的に除外しています。

完全に除外（API トークン／ユーザー／アクセスグループの管理—ネットワークデータではなく、ID と認証情報の管理）—実装していません： GET /token、/token/{tokenId}、/users、/user、/user/totpauth、/access-groups/sites、/access-groups/sites/{groupId}、/nms/keep-alive、/nms/account/login/ubiquiti。

完全に除外（バックアップ、復元、サポートバンドルのダウンロード—バイナリ／機密情報を含み、また、処理元の読み取り操作が GET であっても、復元は保守作業に隣接する書き込み操作であるため）—実装していません： GET /nms/backups、/nms/backups/{backupId}、/nms/backups/{backupId}/download-token、/nms/downloads/{token}、/nms/maintenance/backup、/nms/maintenance/backup/restore、/nms/maintenance/supportinfo、/devices/{deviceId}/backups、/devices/{deviceId}/backups/{backupId}、/devices/{id}/supportfile。

完全に除外（サーバー管理と設定—メールサーバー／SMTP の認証情報やサーバーレベルの設定が含まれる可能性があり、ネットワーク／デバイスのデータではないため）—実装していません： GET /nms/settings、/nms/server-config、/nms/setup、/nms/mailserver、/nms/connection（UISP サーバー自身の接続キーを返します）、/nms/log-verbosity、/nms/update、/nms/update/log、/nms/traffic/blacklist、/nms/traffic/subnets、/nms/address、/nms/search、/nms/news、/nms/blog/posts、/nms/questionnaires/active、/nms/changed、/nms/server-time、/nms/heartbeat（認証不要の稼働確認のみを行うため、代わりにこのコネクターでは、認証済みの健全性確認として uisp_get_version を使用します）。

完全に除外（CRM／請求—独自の顧客請求データモデルを持つ別サブシステムであり、ネットワーク監視コネクターの範囲外であるため）—実装していません： GET /crm/roles、/crm/service-plans。

完全に除外（GDPR／顧客データのエクスポート）—実装していません： GET /gdpr/clients/{id}。これは特定の顧客の個人データを整形してエクスポートするものです。

完全に除外（生のデバイスへのパススルー／UDAPI プロキシ）—実装していません： GET /devices/{deviceId}/udapi/{version}/{udapiUrl*}。これはデバイス自身のローカル API への汎用リバースプロキシです。UISP 自身の仕様では、転送先での GET の意味論に限定されていないため、外側の HTTP メソッドにかかわらず、このカテゴリ全体を除外しています。これは、同様のコンソールごとのコネクター・プロキシパスを unifi-mcp が扱う方法と同じです。

完全に除外（ネットワーク検出のコントロールプレーン）—実装していません： GET /discovery/scan-status、/discovery/status/{deviceId}。これらは、API の別の場所で開始／制御されるネットワークスキャンの実行状況です。検出ワークフロー全体の一部として除外しており、その中から個別に切り分けていません。 対象外（デバイスごとの詳細な設定：DHCP、ファイアウォール、ルーティング、VLAN、NetFlow、無線／AirCube／AirMax／OLT／ONU の設定）—実装しません： /devices/erouters/*、/devices/uisprs/*（DHCP リース／サーバー、ファイアウォールフィルター／マングル／NAT／セット／設定、OSPF、ルート、NetFlow）、/devices/{id}/router/*、/devices/{id}/netflow、/devices/{id}/vlans、/devices/{id}/services、/devices/{id}/system、/devices/{id}/system/unms、/devices/{deviceId}/mac-table*、/devices/{deviceId}/interfaces/{interfaceName}、/devices/{deviceId}/interfaces/data-link/available、/devices/{deviceId}/location 以下のすべての GET と、デバイスモデルごとの詳細／設定／ステーション用エンドポイント群全体（/devices/aircubes/*、/airfibers/*、/airmaxes/*、/blackboxes/*、/epowers/*、/eswitches/*、/olts/*、/onus/*、/solarbeams/*、/toughswitches/*、/uispss/*、/waves/*、さらに /devices/aps/profiles、/devices/ssids、/devices/models、/devices/macs、/devices/ips、/devices/unknown、/devices/import/status）はすべて実装しません。このコネクターのデバイス関連機能は、意図的に識別情報／ステータス／テレメトリー／インターフェース（uisp_list_devices、uisp_get_device、uisp_get_device_detail、uisp_get_device_statistics、uisp_list_device_interfaces、uisp_get_device_by_mac、uisp_list_discovered_devices）に限定しており、ベンダーごとのモデル設定は扱いません。

対象外（主要な6項目を超えるサイトのサブリソース）—実装しません： GET /sites/{id}/images、/sites/{siteId}/images/{imageId}（バイナリ）、/sites/{siteId}/qos、/sites/{siteId}/slastats（UISP 自身の概要では「ISP および SLA スコアのデバッグ用」と説明されています）、/sites/{siteId}/traffic、/sites/{siteId}/traffic/interval、/sites/traffic（このコネクターの目的においては、実装済みの uisp_get_site_traffic_summary で代替されています）。

対象外（計画／シミュレーションおよび現場設置用ツール：稼働中のネットワーク状態ではありません）—実装しません： GET /simulation、/simulation/devices、/simulation/links、/installations/devices、/installations/{id}、/installations/{id}/{mac}/configuration。

対象外（その他）—実装しません： GET /devices/{id}/router/*（上記参照）、/tasks/{batchId}（実装済みの一覧／進行中件数を超えるタスクごとの項目詳細）、/airlink/proxy/*（RF リンク計画用の地図／標高データファイルであり、稼働中のネットワーク状態とは無関係）、/nms/version/latest（新しい UISP リリースの有無を確認するもので、管理用であり、監視データではありません）。

意図的にスコープを決定したうえで、要望があれば後続対応として追加できます。デフォルトでは追加しません。

開発

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

Docker

docker build -t uisp-mcp .
docker run -p 8080:8080 -e UISP_API_KEY=... -e UISP_BASE_URL=https://uisp.example.com uisp-mcp