UniFi

---

「リビングのテレビで動画が止まるのはなぜ？」 テレビはリビングの AP に接続されており、電波強度は -78 dBm、速度は 12 Mbps です。その AP の 5 GHz 無線では、チャネル 36 のチャネル使用率が 81% になっています。AP をチャネル 149 に変更するか、有線バックホールを追加すれば解決できるはずです。チャネルを変更しますか？

ネットワークについて、普段使う言葉で質問できます。アシスタントは145 個のツールから適切なものを選んで情報を調べ、許可されていれば変更も行います。使用例をいくつか紹介します。

• 🩺 「ネットワークのヘルスチェックをしてください。」
• 🔎 「現在、WiFi の電波が弱いクライアントはどれですか？」
• 🔐 「ファイアウォールとポートフォワーディングに危険な設定がないか確認してください。」
• 🔄 「ファームウェアの更新があるデバイスと、最後に再起動した日時を教えてください。」
• 🎟️ 「速度を 5 Mbps に制限した、1 日有効のゲスト用バウチャーを 10 個作成してください。」
• 🧱 「ブロックを解除するまで、「kids-tablet」というデバイスをブロックしてください。」

特長

• 🐳 Docker ファースト。 linux/amd64 および linux/arm64 向けに、小型の distroless イメージ（ghcr.io/mattoddie/unifi-mcp、約 22 MB）を 1 つ用意しています。長時間稼働するサービス向けの Streamable HTTP、または docker run -i 向けの stdio で動作します。Claude Desktop 向けには、Docker 不要のワンクリック拡張バンドル（.mcpb）も用意しています。
• 🛡️ デフォルトで安全。 書き込みを有効にしない限り、サーバーは読み取り専用です。設定の削除には、もう 1 つのスイッチを有効にする必要があります。破壊的な操作を行うツールにはラベルが付いており、MCP クライアントは実行前に確認を求めます。また、出力ではパスワードとキーがマスキングされます。
• 🔍 プレビューと監査。 すべての書き込みツールで dry_run: true を指定すると、変更せずに送信予定のリクエストと、変更内容のフィールド単位の差分を確認できます。UNIFI_AUDIT_LOG を設定すると、各変更が JSON Lines 形式の監査ログに記録されます。
• 🧰 幅広い対応範囲。 14 のツールセットに対応しています。デバイス、クライアント、スイッチポートと PoE、WiFi、ネットワークと VLAN、WAN、DNS、従来型およびゾーンベースのファイアウォール、トラフィックルールとルート、IDS/IPS、VPN、RADIUS、ホットスポットバウチャー、統計情報、ログ、管理者、バックアップを扱えます。
• 🎛️ 調整可能。 必要なツールセットだけを公開できるため、モデルのコンテキストを小さく保ち、用途に集中させられます。ツールリストを小さく保つをご覧ください。
• 🔌 お使いのコントローラーで動作。 UniFi OS コンソール（UDM、UDM Pro/SE、UCG、UDR、UX、Cloud Key Gen2+、UniFi OS Server）と、従来型のセルフホスト型 Network アプリケーションに対応しています。認証には API キーまたはローカルアカウントを使用します。
• 🧪 テスト済み。 ビルドのたびに、モックコントローラーを使ってテストスイートを実行します。

クイックスタート

Docker、UniFi コントローラー、および Claude Code などの MCP クライアントが必要です。

1. 認証情報を取得します。 UniFi OS コンソールで、API キーを作成します：UniFi Network → Settings → Control Plane → Integrations → Create API Key。古いコントローラーでは、代わりにローカルアカウントを使用します。

2. サーバーを起動します。

mkdir unifi-mcp && cd unifi-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/example.env -o .env
# Edit .env: set UNIFI_URL, UNIFI_API_KEY and a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`).
# For an https controller, also say how to check its certificate, or the server won't start.
# Recommended: pin it with UNIFI_TLS_FINGERPRINT (see docs/security.md). example.env sets
# UNIFI_VERIFY_SSL=false, which skips the check: remove it once the fingerprint is set.
docker compose up -d

3. アシスタントに接続します。

claude mcp add --transport http unifi http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Claude Code で 「ネットワークの調子はどう？」 と尋ねてみましょう。

Claude Desktop、VS Code、Cursor、Codex をお使いですか？MCP クライアントの接続をご覧ください。サービスを実行したくない場合は、docker run -i を使った stdio モードをご利用ください。

Claude Desktop をワンクリックで利用

Claude Desktop をインストールした Mac または Windows PC では、Docker は必要ありません。お使いのコンピューター用の .mcpb バンドルを最新リリースからダウンロードして開き、設定でコントローラーの URL、API キー、証明書のフィンガープリントを入力します。Claude Desktopをご覧ください。

unifi-mcp は io.github.mattoddie/unifi-mcp として MCP Registry にも登録されており、イメージ（stdio 経由）とバンドルが公開されています。そのため、レジストリを読み取るクライアントやディレクトリからインストールできます。

変更を有効にする

初期状態では、アシスタントはネットワークを確認できますが、変更はできません。変更を許可するには、これらを .env に追加して docker compose up -d を実行します：

UNIFI_ALLOW_WRITES=true      # restart devices, block clients, edit WiFi/firewall/networks…
UNIFI_ALLOW_DELETES=true     # also allow deleting configuration, forgetting clients… (needs writes too)
UNIFI_TOOLSETS=overview,devices,clients,wifi,monitoring   # optional: expose fewer tools
UNIFI_AUDIT_LOG=stderr       # optional: log every change (or a file path; see docs/configuration.md)

まずドライランを依頼して、変更内容をプレビューします：「ドライラン：ゲスト WiFi を無効にしてください。何が変わりますか？」 本番ネットワークで書き込みを有効にする前に、セキュリティをお読みください。

できること

ツールセット	対応内容
overview	サイト、コントローラー情報、サイトの健全性
devices	デバイスのステータスと詳細、再起動／場所の特定／プロビジョニング、ファームウェアのアップグレード（ローリングアップグレードも含む）、無線、PoE コンセント、採用、RF スキャン、AP グループ
clients	オンラインおよび既知のクライアント、ブロック／ブロック解除、再接続、名前、固定 IP、AP への固定、登録解除
switching	スイッチポート、ポートプロファイル、PoE 電源の再投入、ポートミラーリング、リンクアグリゲーション、LLDP 隣接機器
wifi	WLAN（SSID、セキュリティ、VLAN、帯域）、WiFi QR コード
networks	ネットワーク／VLAN と DHCP、WAN、ローカル DNS レコード、帯域幅プロファイル、ダイナミック DNS
firewall	ポート転送、ファイアウォールルールとグループ、ゾーンベースのポリシーとゾーン、トラフィックルール、QoS ルール、NAT ルール、スイッチ ACL ルール、オブジェクト指向のネットワークポリシー
routing	静的ルート、ポリシーベースのトラフィックルート
security	IDS/IPS 脅威管理、脅威ログ、国別ブロック、コンテンツフィルタリング
vpn	VPN サーバーとサイト間 VPN、RADIUS プロファイルとアカウント
hotspot	バウチャー、ホットスポット運用者、ゲスト認証、ゲストポータル
monitoring	イベント、アラーム、トラフィックレポート、トラフィックフロー、DPI、速度テスト、不正 AP、システムログ、セッション、異常、ダッシュボード
admin	サイト設定（SNMP、mDNS、自動バックアップを含む）、管理者、バックアップ、コントローラーの更新、サイト
raw	任意のコントローラー API パスを呼び出すための拡張手段

すべてのツールと引数については、**ツールリファレンス**をご覧ください。network_health_check、troubleshoot_client、security_review などのすぐに使えるプロンプトでは、一般的な作業向けにツールを連携させています。

ドキュメント

ドキュメントは検索機能付きで、unifi-mcp.mattoddie.dev/docs でも公開されています。

🚀 はじめに	認証情報の設定から最初の質問まで、手順を追って説明します
🔌 MCP クライアントの接続	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio モード
⚙️ 設定	すべての環境変数、Docker シークレット、ツールセット
🐳 デプロイ	Compose、イメージタグ、アップグレード、TLS リバースプロキシ、セキュリティ強化
💬 unifi-mcp の使い方	会話例、プロンプト、保存とシークレットの仕組み
🧰 ツールリファレンス	コードから生成された、全 145 個のツールと 5 個のプロンプト
🛡️ セキュリティ	脅威モデル、最小権限、安全な書き込み設定
📡 互換性	対応コントローラーとバージョン、API に関する注意点
🩹 トラブルシューティング	よくあるエラーとその解決方法
🛠️ 開発	アーキテクチャ、ツールの追加、テスト

コントリビューション

バグ報告、お使いのハードウェアでの互換性レポート、ドキュメントや新しいツールの提供など、あらゆるコントリビューションを歓迎します。始めるにはコントリビューションガイドを読み、行動規範に従ってください。脆弱性の報告については、セキュリティポリシーをご覧ください。脆弱性について、公開 issue は作成しないでください。

ライセンス

MIT © Matt Oddie

unifi-mcp は独立したコミュニティプロジェクトです。Ubiquiti Inc. との提携、同社による承認または後援はありません。UniFi および Ubiquiti は Ubiquiti Inc. の商標です。