rustunifimcp

rustunifimcp

UniFi Network 向けエンタープライズ MCP サーバー — 厳選されたツール、範囲を限定したアクセス、監査可能な変更管理
mechub プロジェクト — 主権性を備えたネットワークセキュリティ自動化

非公式／コミュニティプロジェクト。 これは独立したコミュニティプロジェクトであり、Ubiquiti Inc. との提携や同社による推奨を主張するものではありません。製品名および商標は、本ソフトウェアが連携するシステムを特定する目的でのみ使用しています。

---

rustunifimcp は、mechub MCP サーバーファミリーにおける UniFi Network 向けのメンバーです。 rustjunosmcp が Junos に対して、 rustpanosmcp が PAN-OS に対して提供するものと同様に、単一ベンダーの管理 API に対する、厳選され、範囲が限定され、監査可能な MCP インターフェースを提供します。

mecmcp ネイティブとして構築されており、ローカルの認証、トランスポート、監査、ポリシー、インベントリ、変更管理のコードは一切ありません。これらはすべて、共有 Rust 基盤である mecmcp が担います。ここに記述されているのは、UniFi のリソースモデル、ツール群、ワークフローだけです。それ以外はありません。

UniFi は、ファミリー内で候補設定がまったくない最初のベンダーです。ステージング領域も、コミットも、オンボックス検証もありません。Junos と PAN-OS には候補設定とコミットがあり、Proxmox と Security Director には承認を紐付けられるサーバー側のタスクセマンティクスがあります。一方、UniFi にはライブ設定に対する即時の REST 書き込みしかありません。このため、mecmcp-changeset が、それを生み出した 2 つのベンダーを超えて汎用化できるかを試す、真の試金石となります。

状況

メンテナーのインフラストラクチャで日常的に使用中（アルファ版）。レガシーサーバーへの依存は解消済みです。

rustunifimcp v0.6.6 は、読み取り、ワークフロー、運用アクション、変更管理の全機能を、2 台の本番ゲスト（ラボモードの LXC 981 と、二者承認制の LXC 982）から TLS 経由で提供します。 unifi-mcp-legacy の登録は削除済みで、Python サーバーにルーティングされるものはもうありません。

LXC 980 自体には手を加えておらず、現在も稼働中です。 notmechub;protected のタグが付いており、変更する権限はもともとありませんでした。依存関係の解消は、ゲストに対して操作することを意味していません。ロールバック経路として残してあり、登録を再追加すれば以前の機能が復元されます。停止または破棄するかどうかは、所有者が別途判断します。

ゲスト	役割	エンドポイント
981 prod-unifimcp	日常使用のラボゲスト、--lab-mode、TLS	https://prod-unifimcp.example.org:30033/mcp
982 prod-unifi2mcp	日常使用のラボゲスト、二者承認制、TLS	https://prod-unifi2mcp.example.org:30033/mcp
622 test-twoperson-unifi	テスト環境、二者承認制	http://test-twoperson-unifi.example.org:30033/mcp
623 test-labmode-unifi	テスト環境、--lab-mode	http://test-labmode-unifi.example.org:30033/mcp

レガシー機能との同等性については docs/PARITY-AUDIT.md に記録しています。使用期間中のレガシーツール 33 個のうち、31 個は実装され、稼働中のコントローラーで検証済みです。1 個は実装済みですが未検証です（execute_port_action。unifi_device_action action=port_action として利用可能です。PoE の電源再投入のみで、--allow-direct-commit が必要です。使用中のスイッチポートに影響するため、稼働環境では実行していません）。残り 1 個は許容済みの未対応項目です（set_device_port_overrides。10.5.67 には検証済みの書き込み経路がありません）。

ドキュメント	内容
PLAN.md	フェーズの順序と 2 回の切り替えの概要
docs/HOW-TO-SETUP-LXC.md	rustunifimcp の Proxmox LXC をゼロから構築する方法
docs/HOW-TO-SETUP-DOCKER.md	二者承認制およびラボモードで rustunifimcp を Docker 上で実行する方法
docs/superpowers/specs/2026-08-26-rustunifimcp-cutover-design.md	構築と切り替えの設計：デプロイのトポロジー、コントローラーの信頼性、各フェーズの詳細、リスク
docs/superpowers/specs/2026-07-24-rustunifimcp-design.md	当初の設計。ツール機能、API タグ付け、変更管理への適応について、引き続き正式な指針となります

サポート対象となる最低コントローラーバージョン

サポート対象の最低バージョン：UniFi Network Application 10.5.67／UniFi OS Server 5.1.37

このサーバーを使用するには、UniFi Network コントローラーが UniFi Network Application 10.5.67 以上、または UniFi OS Server 5.1.37 以上で稼働している必要があります。これらのバージョンには、このプロジェクトが安全な API アクセスのために依存する 2026 年の CVSS 10 セキュリティ修正（SAB-062、SAB-064、SAB-066/067）が含まれています。

最低バージョンは、rustunifimcp のテスト環境とフィクスチャセットで検証済みです。これより古いバージョンのコントローラーで実行すると、エンドポイントが利用できなかったり、API の変更に対処できなかったりする場合があります。

置き換える対象

ホームラボでは enuno/unifi-mcp-server（Python / FastMCP）を実行しています。これは優れた API クライアントですが、このプロジェクトが解決するべき問題が 2 つあります。

ツールの乱立。 レジストリはリフレクションによって src/tools/ 内のすべてのパブリックな非同期関数を自動登録します。37 個のモジュールにある 205 個の関数が、約 270 個の MCP ツールになります。この数を誰も選んだわけではありません。rustunifimcp が目指すのは 22 個です。リソース列挙型を使った型付き読み取りプリミティブ、変更管理ライフサイクル、スコープを限定した運用アクション、そしてその名にふさわしい 4 つのワークフローです。22 個すべてがエンドツーエンドで実際に動作し、公開されているのに、呼び出すたびに拒否されたり空の結果を返したりするものはありません。

MCP レイヤーのセキュリティがない。 ベアラートークン、スコープ、監査証跡、レート制限なしで、平文 HTTP をリッスンします。ポートに接続できるものはすべて、コントローラーへの無制限の書き込みアクセス権を持ちます。rustunifimcp では、完全な mecmcp セキュリティレイヤーを継承しています。

ツールカタログ

読み取りプリミティブです。unifi_list_resources と unifi_get_resource の背後にある、統合されたインターフェースです。すべての kind はモデルに渡される前に、rustunifimcp-core::redact に記載された許可リストまたはスキャンを通じて処理されます。詳しくは、以下の設計上の特長をご覧ください。

ツール	備考
unifi_list_resources	kind = station | device | network | wlan | port_profile | dhcp_reservation | firewall_policy | firewall_zone | firewall_group | firewall_rule | port_forward | static_route | traffic_route | radius_profile
unifi_get_resource	kind、id
unifi_query_stats	subject = site | device | station | wlan | flow | event、および時間範囲
unifi_search	ステーション、デバイス、サイトを対象とするフリーテキスト検索
unifi_list_sites

firewall_rule、port_forward、static_route（MEC-509）は、従来型（ゾーンベースではない）のルールセット、ポートフォワーディングルール、静的ルートです。現時点では読み取り専用であり、unifi_stage_change を通じた書き込みルートはありません。subject=event はコントローラーのイベントログにアクセスします。

unifi_backup_action（MEC-516）は list と trigger を接続します。list はコントローラーに保持されているバックアップを返します。ほかのリスト形式のツールと同様に、最大 100 件に制限され、truncated マーカーが付与されます。trigger は新しいバックアップを開始します。download と validate は一切提供されません（MEC-505：公開したうえで拒否するのではなく、アクション列挙型から削除済みです）。どちらも JSON ではなく生の .unf ファイルを移動する必要がありますが、このサーバーはまだ対応していません。restore は今後も拒否されます。バックアップを復元すると設定全体が上書きされるため、変更セットのライフサイクルを通じて実行します。

Docker で実行する（stdio）

カタログ向けの stdio 呼び出しでは、イメージの HTTP CMD を --transport stdio に置き換えます。controllers.json（形式： packaging/examples/controllers.example.json）とコントローラー API キーファイルを etc/ に配置し、変更セットと監査 HMAC キー用に、コンテナが書き込み可能な state/ ディレクトリを用意します。どちらもイメージの UID/GID 65532:65532 が所有し、ファイルのモードを 0600 にする必要があります。

mkdir -p etc state
# etc/controllers.json  -> "api_key_file": "/etc/unifimcp/api.key"
# etc/api.key           -> the controller API key
sudo chown -R 65532:65532 etc state
sudo chmod 0700 etc state
sudo chmod 0600 etc/controllers.json etc/api.key

docker run --rm -i \
  -v "$PWD/etc:/etc/unifimcp:ro" \
  -v "$PWD/state:/var/lib/unifimcp" \
  ghcr.io/mechubsec/rustunifimcp:latest \
  --transport stdio

サーバーは MCP レジストリに io.github.mechubsec/rustunifimcp として登録されています。そのエントリーは、この stdio コマンドをそのまま実行します。同じイメージは Docker Hub でも docker.io/mechub/rustunifimcp として公開されています。

stdio では呼び出し元の ID が伝達されないため、変更セットの承認と直接コミットするツールは拒否されます。二者承認による変更管理には、docs/HOW-TO-SETUP-DOCKER.md に記載されたストリーム可能な HTTP の設定を使用してください。

設計の特徴

それぞれにラベルを付けた3つの API サーフェス。 UniFi がサポートする Integration API は、コントローラーが実際に実行できる操作よりもはるかに限定的なため、プライベートな /api/s/ と /v2/api/ のルートも含めています。ただし、すべてのエンドポイントにはコード内でタグを付け、プライベートなエンドポイントはトークンのスコープではなく、controllers.json のコントローラーごとの明示的な allow_private_api フラグによって制限しています。サポート対象の API のみを使う構成は、実際に実行可能な構成であり、コントローラーのアップグレードによって気付かないうちに動作しなくなることはありません。

実態に即した変更管理。 UniFi には候補設定もコミットもありません。変更セットのライフサイクルは、クライアント側での変更前状態の取得、ローカルでの検証、順次適用、ベストエフォートのロールバックによって実装されており、ツールの説明にもその旨を記載しています。UniFi の変更セットを承認するオペレーターは、コミット確認付きの動作を得るわけではなく、サーバーもそのように装っていません。unifi_approve_change_set には人間の承認者が必要です。サーバーは呼び出し元のトークンの actor_type を mecmcp に渡し、mecmcp は agent または呼び出し元を特定できない（stdio）呼び出し元からの承認を拒否します。承認できるのは actor_type: human の場合だけです。rustunifimcp token add ... --actor-type human で承認者のトークンを発行してください。actor_type は発行時にオペレーターが設定するクレームであり、サーバーが証明するものではありません。human とタグ付けされたトークンを LLM エージェントに渡せば、この制限を回避できてしまいます。

マルチコントローラー。 コントローラーは環境変数ではなくインベントリレジストリで管理されるため、1つのインスタンスで複数のコントローラーに接続でき、トークンのスコープをその一部に限定できます。

HTTP のデフォルト設定では制限を適用し、無制限にはしません。 IP ごとおよびトークンごとのリクエストレート、同時セッション数、リクエストボディサイズの上限はすべてデフォルトで適用されます（LimitsConfig::default()）。各制限は CLI フラグでも指定できるため（rustunifimcp --help を参照）、フォークせずにオペレーターが調整できます。認証不要の /healthz（プロセスの稼働状態）と /readyz（依存関係のチェックが設定されていないため、「準備完了」は「稼働中」と同じ状態を示します）は常にマウントされます。/metrics はデフォルトで無効です（--enable-metrics）。有効にした場合も、ループバックからの呼び出しに制限されます。

ライセンス

MIT のライセンスに基づいています。