UniFi RMCP

unifi-rmcp

MCP と CLI を通じた UniFi ネットワークのクライアント、デバイス、WLAN、ファイアウォール、ヘルス操作です。

1 つの MCP ツール unifi と、runifi CLI を提供します。エージェントはクライアント、デバイス、WiFi ネットワーク、ヘルス、アラーム、イベント、コントローラーのシステム情報、認証済みの本人情報を確認でき、MCP 認証スコープで許可されている場合は、生成された official_* / unifi_* アクションを使用できます。

30 秒で始める方法： UNIFI_URL と UNIFI_API_KEY を設定し、npx -y @dinglebear/runifi health --json を実行します -> UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve でループバック HTTP を起動します -> {"action":"health"} を指定して tools/call を呼び出します。

ステータス： 運用可能な RMCP アップストリームクライアントサーバーです。保持されている利便性向上のためのアクションは読み取りを中心としており、生成された変更を伴うアクションには unifi:admin 認可が必要です。HTTP MCP は、ループバック開発モード、静的ベアラートークン、lab-auth を介した Google OAuth に対応しています。

対象外： UniFi コンソールの置き換え、呼び出し元のコントローラー認証情報の保存、UniFi 権限の回避、汎用 HTTP プロキシ、マルチテナントの分離、MCP ツール引数を介した UniFi API キーの受け渡し。

目次

• 命名
• 機能と制限
• インストール
• クイックスタート
• クライアント設定
• ランタイムのインターフェース
• MCP ツールのリファレンス
• CLI リファレンス
• 設定
• 認証
• 安全性と信頼モデル
• アーキテクチャ
• 配布契約
• 開発
• 検証
• デプロイ
• トラブルシューティング
• 関連サーバー
• ドキュメント
• ライセンス

命名

インターフェース	このリポジトリ
リポジトリ	unifi-rmcp
Rust クレート	unifi-rmcp
バイナリ / CLI	runifi
npm パッケージ	@dinglebear/runifi
npm バイナリのエイリアス	unifi-rmcp、runifi
MCP ツール	unifi
設定ディレクトリ	ホストでは ~/.unifi-rmcp、コンテナでは /data
環境変数のプレフィックス	npm ランチャーの制御には UNIFI_*、UNIFI_MCP_*、UNIFI_RMCP_*

リポジトリと npm パッケージでは RMCP ファミリー名を使用しますが、配布バイナリでは短い Rust CLI 名 runifi を使用します。

機能と制限

• 接続済みの無線および有線クライアント、ネットワークデバイス、WLAN 設定、サイトのヘルス、アクティブなアラーム、最近のイベント、コントローラーのシステム情報、現在の認証済みユーザーを読み取ります。
• 文書化されている Network Integration API エンドポイント向けに、生成された official_* アクションをディスパッチします。
• モデルベースの unifi_* 内部コントローラーアクションと、list_clients、list_devices、list_networks、list_wifi、get_system_info などのハイブリッドエイリアスをディスパッチします。
• マウントされた HTTP MCP モードでは、読み取りアクションに unifi:read、変更を伴うアクションに unifi:admin を適用します。
• ローカルのランタイム確認用に、セットアップ、診断、エンドポイント検証のコマンドを提供します。

このリポジトリが担うもの	UniFi が担うもの	明示的な対象外
MCP/CLI の投影、アクションレジストリ、リクエスト検証、HTTP MCP 認証ポリシー、レスポンス整形、生成アクションのディスパッチ、セットアップ確認、エンドポイント検証。	コントローラーの状態、サイト / デバイス / クライアントのデータ、UniFi ユーザー、API キーの発行、アップストリーム認可、実際のネットワーク変更。	コントローラー UI の置き換え、認証情報の仲介、任意の HTTP プロキシ、長時間のポーリング、ポリシー・アズ・コード、マルチテナントのサンドボックス化、ローカルゲートウェイのプロビジョニング。

インストール

方法	コマンド	最適な用途	備考
npm / npx	npx -y @dinglebear/runifi --help	ローカル MCP クライアントでの利用や簡単な試用。	GitHub Releases から一致する runifi バイナリをダウンロードします。
リリースインストーラー	curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/runifi/main/scripts/install.sh | bash	Node を使わないホストへのインストール。	現在の Linux ホストに runifi をインストールします。
Docker / Compose	docker compose up -d	共有 HTTP MCP のデプロイ。	.env を読み込み、コンテナーのポート 40030 を公開します。
ソースからビルド	cargo build --release	開発や監査。	target/release/runifi を生成します。
プラグイン	claude plugin install plugins/unifi	このチェックアウトから Claude Code のローカルプラグインをセットアップする場合。	スキルと .mcp.json が含まれます。セッションフックはありません。プラグインの設定は .mcp.json の ${user_config.*} 環境変数ブロックを通じてサーバーに渡されるため、手動でのセットアップは不要です。

npm / npx

バイナリを手動でインストールせずに、stdio MCP サーバーまたは CLI を実行します。

npx -y @dinglebear/runifi --help
npx -y @dinglebear/runifi mcp
npx -y @dinglebear/runifi health --json

npm パッケージは postinstall 中に runifi をダウンロードします。ダウンロードの動作を上書きするのは、パッケージングのテスト時に限ってください。

変数	用途
UNIFI_RMCP_SKIP_DOWNLOAD=1	postinstall によるバイナリのダウンロードをスキップします。
UNIFI_RMCP_VERSION または UNIFI_RMCP_BINARY_VERSION	GitHub Release のタグを選択します。
UNIFI_RMCP_REPO	リリースのダウンロードに使用する GitHub リポジトリを選択します。
UNIFI_RMCP_RELEASE_BASE_URL	カスタムのリリースベース URL を選択します。

ソースからのビルド

git clone [email protected]:dinglebear-ai/runifi.git
cd runifi
cargo build --release
./target/release/runifi --help

サポートされる Rust の最小バージョンは 1.86 です。Cargo ワークスペースには、ルートの unifi-rmcp パッケージ、crates/unifi（再利用可能なコア）、xtask（開発ツール）の 3 つのメンバーがあります。すべてのメンバーは、ワークスペースのルートから Rust エディション 2024 と MSRV 1.97.1 を継承します。

クイックスタート

1. UniFi API キーを作成する

UniFi OS で「Settings」->「Admins & Users」->「API Keys」に移動し、キーを作成して UNIFI_API_KEY にコピーします。

2. コントローラーを設定する

export UNIFI_URL=https://unifi.local
export UNIFI_API_KEY=...
export UNIFI_SITE=default
export UNIFI_SKIP_TLS_VERIFY=true

/proxy/network パスプレフィックスを使用しない古い非 UDM コントローラーの場合にのみ、UNIFI_LEGACY=true を設定します。

3. 安全な CLI 呼び出しを実行する

npx -y @dinglebear/runifi health --json

4. ループバック HTTP MCP を起動する

UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve

別のシェルで実行します。

curl -sf http://127.0.0.1:40030/health

5. 最初の MCP 呼び出しを行う

curl -s -X POST http://127.0.0.1:40030/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"unifi","arguments":{"action":"health"}}}'

クライアント設定

Claude Code の Stdio

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "unifi-rmcp", "mcp"],
      "env": {
        "UNIFI_URL": "https://unifi.local",
        "UNIFI_API_KEY": "...",
        "UNIFI_SITE": "default",
        "UNIFI_SKIP_TLS_VERIFY": "true"
      }
    }
  }
}

Claude Code の HTTP

{
  "mcpServers": {
    "unifi": {
      "type": "http",
      "url": "http://127.0.0.1:40030/mcp",
      "headers": {
        "Authorization": "Bearer ${UNIFI_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby ゲートウェイ

1 つの長時間実行サーバーを共有する場合は、Labby を通じて UniFi を HTTP アップストリームとして登録します。ローカルのみで使う場合は、stdio として直接実行します。

[mcp_servers.unifi]
command = "npx"
args = ["-y", "unifi-rmcp", "mcp"]

汎用 MCP JSON

{
  "command": "runifi",
  "args": ["mcp"],
  "env": {
    "UNIFI_URL": "https://unifi.local",
    "UNIFI_API_KEY": "..."
  }
}

UNIFI_API_KEY、OAuth シークレット、パスワード、SSH キー、アップストリームのベアラートークンを MCP ツールの引数に含めないでください。環境変数、設定ファイル、または MCP クライアントのシークレットストレージを使用してください。MCP の呼び出し元が、アクションの引数として認証情報、トークン、キー、シークレットを渡すことはありません。

実行サーフェス

サーフェス	状態	エントリーポイント	用途
MCP stdio	サポート対象	runifi mcp、npx -y @dinglebear/runifi mcp	ローカルの子プロセス型 MCP クライアント。
MCP HTTP	サポート対象	runifi serve、POST /mcp	ローカルまたは共有サーバーのデプロイ向け Streamable HTTP MCP。
CLI	サポート対象	runifi <command>	スクリプトからの同等操作とデバッグ。
プロンプト	サポート対象	network_summary	UniFi のステータスを要約するエージェント用プロンプト。
リソース	サポート対象	MCP ツールスキーマのリソース	クライアント側でのスキーマ検出。
REST API	提供なし	N/A	UniFi がすでに REST API を提供しています。
Web UI	提供なし	N/A	UniFi がすでにコントローラー UI を提供しています。

MCP ツールリファレンス

公開されている MCP ツールは 1 つです。unifi。必須の action 引数を渡して操作を選択します。アクションの列挙値は data/ のインベントリから生成されるため、対象範囲は広範です。

ファミリー	アクション数	変更を伴う
official_*	78	36
unifi_*	175	87
保持された便利アクション	8	0
ハイブリッドエイリアス	5	0
help	1	0
合計	267	123

件数は data/unifi_official_network_v10_3_58.json と data/unifi_internal_endpoint_models.json の runtime: true エントリーから算出されています。 実行時の信頼できる情報源は crates/unifi/src/capabilities.rs です。

保持された便利アクション

アクション	説明	必須パラメーター	オプションのパラメーター
clients	接続中の無線および有線クライアント。	なし	なし
devices	ネットワークデバイス：AP、スイッチ、ゲートウェイ。	なし	なし
wlans	WiFi ネットワークの設定。	なし	なし
health	サイトの健全性の概要。	なし	なし
alarms	有効なアラームとアラート。	なし	なし
events	コントローラーの最近のイベント。	なし	limit
sysinfo	コントローラーのシステム情報。	なし	なし
me	認証済みの UniFi ID。	なし	なし
help	組み込みのアクションドキュメント。	なし	なし

生成されるアクションファミリー

ファミリー	説明	スコープの動作
official_*	/proxy/network/integration/v1 配下の、文書化された Network Integration API の操作。	読み取り操作には unifi:read、変更を伴う操作には unifi:admin が必要です。
unifi_*	/proxy/network/api/s/{site} および /proxy/network/v2/api/site/{site} 配下の、モデルに基づく内部コントローラー互換アクション。	読み取り操作には unifi:read、変更を伴う操作には unifi:admin が必要です。
ハイブリッドエイリアス	list_clients、list_devices、list_networks、list_wifi、get_system_info。	デフォルトでは内部アクションを使用します。siteId または params.prefer="official" が指定されている場合は公式 API を使用します。

エンドポイントの対応状況は docs/unifi_api_coverage.md で追跡されています。コントラクトと安全な実環境での検証については docs/unifi_endpoint_verification.md に記載されています。

CLI リファレンス

バイナリは MCP ツールと同じサービスレイヤーを呼び出します。

runifi clients [--json]
runifi devices [--json]
runifi wlans [--json]
runifi health [--json]
runifi alarms [--json]
runifi events [--limit N] [--json]
runifi sysinfo [--json]
runifi me [--json]
runifi official_list_clients --param siteId=<uuid> --json
runifi official_create_network --param siteId=<uuid> --body-json '{"name":"IoT"}' --json
runifi list_clients --param siteId=<uuid> --json
runifi doctor [--json]
runifi setup check [--json]
runifi setup repair [--json]
runifi setup install [--json]
runifi setup plugin-hook [--no-repair] [--json]

生成されたアクションは --param k=v、--body-json JSON、--json を受け付けます。

setup plugin-hook は CLAUDE_PLUGIN_OPTION_* 環境変数を UNIFI_* にマッピングし、~/.local/bin にあるバイナリのコピーを更新して、check と repair を実行します。以前は Claude Code の SessionStart／ConfigChange フックから自動的に実行されていましたが、これらのフックは削除されています。

プラグインを設定するために、これを実行する必要はありません。plugins/unifi/.mcp.json が ${user_config.*} を通じてプラグインの設定をサーバーの環境変数に直接マッピングします。~/.local/bin のバイナリを更新する場合や、事前チェックを実行する場合に限り、手動で実行してください。

設定

設定はまず config.toml から読み込まれ、その後、UNIFI_* 環境変数で上書きされます。ホストにインストールした場合は、設定を読み込む前に ~/.unifi-rmcp/.env を読み込みます。コンテナでは /data/.env を読み込みます。プロセス環境変数は、これら両方の設定を上書きします。

変数	デフォルト	用途
UNIFI_URL	未設定	コントローラーのベース URL（例：https://unifi.local）。
UNIFI_API_KEY	未設定	X-API-KEY ヘッダーに使用する API キー。
UNIFI_SITE	default	UniFi のサイト名。
UNIFI_SITE_ID	未設定	ライブテストと明示的な生成呼び出しで使用する公式 API のサイト UUID。
UNIFI_SKIP_TLS_VERIFY	true	自己署名証明書を使用するコントローラーの TLS 証明書検証をスキップします。
UNIFI_LEGACY	false	/proxy/network プレフィックスを使用しないレガシーコントローラーモード。
UNIFI_MCP_HOST	0.0.0.0	HTTP のバインドホスト。
UNIFI_MCP_PORT	40030	HTTP のバインドポート。
UNIFI_MCP_TOKEN	未設定	HTTP MCP 用の静的ベアラートークン。
UNIFI_MCP_NO_AUTH	false	ループバックでの開発時に限り、認証を無効にします。
UNIFI_MCP_DISABLE_HTTP_AUTH	false	UNIFI_MCP_NO_AUTH との互換性を保つための別名。
UNIFI_NOAUTH	false	上流のゲートウェイが認証を適用することを信頼します。
UNIFI_MCP_ALLOWED_HOSTS	空	カンマ区切りの Host ヘッダー許可リスト。
UNIFI_MCP_ALLOWED_ORIGINS	空	カンマ区切りの CORS Origin 許可リスト。
UNIFI_MCP_PUBLIC_URL	未設定	OAuth メタデータ用の公開 URL。
UNIFI_MCP_AUTH_MODE	bearer	bearer または oauth。
UNIFI_MCP_GOOGLE_CLIENT_ID	未設定	Google OAuth クライアント ID。
UNIFI_MCP_GOOGLE_CLIENT_SECRET	未設定	Google OAuth クライアントシークレット。
UNIFI_MCP_AUTH_ADMIN_EMAIL	未設定	OAuth の初期設定に使用する管理者メールアドレス。
UNIFI_MCP_AUTH_SQLITE_PATH	/data/auth.db	OAuth 状態データベースのパス。
UNIFI_MCP_AUTH_KEY_PATH	/data/auth-jwt.pem	OAuth JWT 署名鍵のパス。
UNIFI_MCP_HOME	~/.unifi-rmcp	アプリデータディレクトリの上書き設定。setup のみが読み込みます。

環境変数による上書きがない config.toml 専用の設定：mcp.server_name と [mcp.auth] の TTL、レート制限、許可リストの各フィールド（access_token_ttl_secs、refresh_token_ttl_secs、auth_code_ttl_secs、register_rpm、authorize_rpm、disable_static_token_with_oauth、allowed_emails、allowed_client_redirect_uris）。config.example.toml を参照してください。

xtask のエンドポイント検証では、サーバーが参照しない独自の変数を読み込みます：UNIFI_ALLOW_INSECURE_TLS、UNIFI_RESOLVE_IP、UNIFI_VERIFY_TIMEOUT_SECS、UNIFI_VERIFY_RATE_LIMIT_MS、UNIFI_VERIFY_MAX_REQUESTS、UNIFI_VERIFY_UNVERIFIED_INTERNAL。

認証

Stdio MCP はローカルの信頼された子プロセスとして実行され、HTTP 認証は使用しません。

HTTP MCP の認証ポリシー：

状態	条件	動作
ループバック開発	UNIFI_MCP_HOST が 127. で始まるか、ループバックで認証が明示的に無効化されている	ローカルでの未認証開発が許可されます。
ベアラー認証で公開	ループバック以外で UNIFI_MCP_TOKEN が設定されている	Authorization: Bearer <token> とアクションスコープが必要です。
OAuth で公開	UNIFI_MCP_AUTH_MODE=oauth	lab-auth を通じて Google OAuth/JWT を使用します。
信頼されたゲートウェイ	UNIFI_NOAUTH=true	リバースプロキシまたはゲートウェイがすでに認証を適用しているものとみなします。

unifi:admin は unifi:read を満たしますが、unifi:read では変更を伴うアクションを実行できません。

安全性と信頼モデル

• UniFi API キーは設定または環境変数からのみ読み込まれます。
• MCP 呼び出し元が選択するのはアクション、パラメーター、リクエスト本文であり、上流の認証情報ではありません。
• 維持されている便利なアクションは読み取り専用です。
• 生成された変更を伴うアクションには、公開された HTTP MCP モードで unifi:admin が必要です。
• 不明なアクションや不正な生成アクションのパラメーターは、上流への呼び出し前にエラーになります。
• ループバック以外で HTTP を公開する場合は、ベアラー認証、OAuth、または認証済みの信頼されたゲートウェイを使用する必要があります。
• このブリッジは UniFi 自体をサンドボックス化しません。API 権限と、変更を伴う呼び出しによる実際のネットワーク側の影響については、引き続き UniFi が管理します。

アーキテクチャ

Capabilities   (src/capabilities.rs)   official/internal/hybrid registry
      |
UnifiClient    (src/api.rs, src/unifi.rs) HTTP path families and transport
      |
UnifiService   (src/app.rs)            action execution boundary
      |
MCP shim       (src/mcp/tools.rs)      JSON args -> service -> Value
CLI shim       (src/cli.rs)            argv -> service -> stdout

配布契約

• Cargo.toml、Cargo.lock、packages/unifi-rmcp/package.json、 .release-please-manifest.json、および server.json のリリースバージョンは一致している必要があります。
• GitHub Releases では、npm ランチャーが使用する runifi バイナリを公開します。
• npm パッケージ名は @dinglebear/runifi です。バイナリエイリアスは @dinglebear/runifi と runifi です。
• Docker/OCI メタデータでは ghcr.io/dinglebear-ai/runifi:<version> を使用します。GHCR の名前空間は、.github/workflows/docker-publish.yml が公開先としているため、引き続き jmagar です。git のリモートは dinglebear-ai/runifi です。片方だけを「修正」しないでください。
• plugins/unifi/.mcp.json では、stdio クライアントが HTTP サーバーではなく MCP トランスポートを開始するよう、npx -y @dinglebear/runifi mcp を起動する必要があります。
• plugins/unifi/ には Claude Code フックは含まれていません。scripts/validate-plugin-layout.sh と tests/setup_cli.rs は、hooks/ ディレクトリまたはマニフェストの hooks キーが再び追加された場合、どちらも失敗します。
• ルートの README は厳選された内容です。現在のアクションと生成されるエンドポイントの対応範囲に関する信頼できる情報源は、src/capabilities.rs、data/ インベントリ、 docs/unifi_api_coverage.md、および docs/unifi_endpoint_verification.md です。

開発

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/unifi-rmcp run check

検証

npm --prefix packages/unifi-rmcp run check
cargo check
cargo test
cargo clippy -- -D warnings
just validate-plugin
cargo run -p xtask -- verify-api-endpoints --mode contract
git diff --check

ライブ読み取りプローブにはコントローラーが必要です：

UNIFI_URL=https://<gateway> \
UNIFI_API_KEY=<network-api-key> \
UNIFI_SITE=default \
UNIFI_SITE_ID=<official-site-uuid> \
UNIFI_SKIP_TLS_VERIFY=true \
cargo run -p xtask -- verify-api-endpoints --mode safe_live

デプロイ

ローカル開発ではループバックを使用してください：

UNIFI_MCP_HOST=127.0.0.1 runifi serve

HTTP を共有してデプロイする場合は Docker Compose を使用してください：

cp .env.example .env
docker compose up -d

ループバック以外のアドレスにバインドする場合は、認証済みゲートウェイの背後で UNIFI_MCP_TOKEN、 UNIFI_MCP_AUTH_MODE=oauth、または UNIFI_NOAUTH=true を設定してください。

トラブルシューティング

症状	確認事項
UNIFI_URL または UNIFI_API_KEY が設定されていない	環境変数または ~/.unifi-rmcp/.env に設定してください。
UniFi コントローラーへの TLS エラー	コントローラーに信頼できる証明書がない場合は、UNIFI_SKIP_TLS_VERIFY=true のままにしてください。
レガシーコントローラーのパスで失敗する	古い非 UDM コントローラーでは UNIFI_LEGACY=true を設定してください。
HTTP /mcp が未認証を返す	UNIFI_MCP_TOKEN を設定し、Authorization: Bearer <token> を送信してください。
stdio クライアントが応答しない、または JSON エラーをログに記録する	クライアント設定で、デフォルトの HTTP サーバーモードではなく unifi-rmcp mcp を実行するようにしてください。
生成された公式アクションで siteId が必要になる	--param siteId=<uuid> または MCP の params.siteId を渡してください。
生成された変更アクションが禁止されている	unifi:admin を持つ HTTP MCP トークン／セッションを使用してください。

関連サーバー

すべての関連サーバーは dinglebear-ai 組織にあります。

• soma - プロバイダー連携型 MCP サーバー向けの RMCP ランタイムおよびスキャフォールド。
• rtailscale - デバイス、ユーザー、tailnet 操作用の Tailscale API ブリッジ。
• unraid - Unraid モノレポ。unraid-rs/ は GraphQL ブリッジです（バイナリ名は runraid）。
• rapprise - 多数の配信バックエンドに通知を振り分ける Apprise ブリッジ。
• rgotify - 送信、メッセージ、アプリ、クライアント向けの Gotify プッシュ通知ブリッジ。
• rarcane - コンテナーおよび関連リソース向けの Arcane Docker 管理ブリッジ。
• yarr - Sonarr、Radarr、Prowlarr、Plex、および関連サービス向けのメディアスタックブリッジ。
• rytdl - メディアのダウンロードとメタデータ処理のワークフローサーバー。
• synapse - scout および flux アクション向けのローカル Synapse ワークフローサーバー。
• cortex - Syslog とホームラボのログ集約を行う MCP サーバー。
• axon - RAG、クロール、スクレイピング、抽出、セマンティック検索のプロジェクト。
• labby - ホームラボのコントロールプレーンおよび MCP ゲートウェイのプロジェクト。

ドキュメント

• CLAUDE.md は、コントリビューターとエージェント向けに編集されたローカル運用ガイドです。
• docs/unifi_api_coverage.md は、API ファミリーとカバレッジの概要をまとめたガイドです。
• docs/unifi_endpoint_verification.md は、エンドポイント検証ガイドです。
• docs/SETUP.md は、プラグインとセットアップに関するガイドです。
• docs/OAUTH.md は、OAuth セットアップに関するガイドです。
• plugins/unifi/skills/unifi/SKILL.md は、エージェント向けの使用ガイドです。
• data/ のインベントリーは、アクションレジストリーの生成元および参照用入力です。
• 現在のアクションディスパッチ、設定のデフォルト値、認証動作、CLI の解析については、src/ が信頼できる情報源です。

ライセンス

このプロジェクトのうち、Dinglebear が作成したオリジナル部分は AGPL-3.0-only の下でライセンスされています。AGPL の範囲外の条件が必要な組織向けに、別途商用ライセンスを用意しています。サードパーティの素材は、それぞれの元のライセンスに従います。詳しくは LICENSING.md をご覧ください。