Unifi MCP Server

UniFi MCP サーバー

Model Context Protocol を通じて、UniFi ネットワークを AI ネイティブに制御

UniFi Network、UniFi Protect、UniFi クラウド API（Site Manager、Mobility、InnerSpace、Carrier Fabric）を MCP ツールとして公開する MCP サーバーです。AI エージェントは、単一の標準インターフェースを通じて UniFi インフラストラクチャの情報を取得・変更できます。単一のコントローラーに接続するほか、フリートモードでは複数のコントローラーに接続して動作します。

現在のリリース：0.6.4。 変更点についてはCHANGELOG.mdをご覧ください。

目次

• 機能
• API モード
• クイックスタート
• エージェントスキル
• ツールプロファイルと安全制御
• ネットワークトランスポートとデプロイ
• コードからサーバーを呼び出す
• ネイティブ MCP プロンプト
• ドキュメント
• 開発

機能

ローカルモードで60個のモジュールから343個のツールを利用できます。

• ネットワーク： クライアント（検索、ブロック、再接続）、ネットワークとVLAN、Wi-Fi SSID、DHCP予約、DNS、WAN、ゲスト用バウチャー、QoSプロファイルとトラフィックルート、DPI統計、トラフィックフロー。
• デバイス： インベントリ、採用、再起動、場所の特定、アップグレード、無線設定、ポートプロファイルとポートごとの上書き設定、スイッチングとスタック、トポロジーのエクスポート（JSON、GraphML、DOT）、診断、Wi-Fiチャネル計画。
• セキュリティ： 従来のファイアウォールルールとグループ、ゾーンベースのファイアウォール（ゾーン、ポリシー、ゾーンマトリックス）、ACLルール、トラフィックマッチングリスト、ポート転送、VPNとサイト間VPN、コンテンツフィルタリング、RADIUSとゲストポータル。
• Protect： カメラ、NVR、ビュー、イベント、センサー、ライト、チャイム、サイレン、リレー、スピーカー、アラームハブ、アラームマネージャー。
• クラウド： Site Manager（ホスト、サイト、サイト横断統計）、コネクタープロキシ、Mobility のワークスペースとデバイス、InnerSpace のフロアプランとインベントリ、Carrier Fabric の加入者とサービスプラン。
• 運用： サイト、バックアップ（作成、スケジュール設定、ダウンロード、復元）、イベント、複数サイトの集約、サイト間でのデバイス移行。
• フリートモード（オプション、PostgresとRedisが必要）：1台のサーバーの背後に複数のコントローラーを配置し、暗号化された認証情報を持つコントローラーレジストリ、ロール付きのサーバー発行トークン、共有読み取りキャッシュ、複数のレプリカとバックグラウンドワーカー、コントローラー間を読み取るfleet_*ツールを利用できます。MULTI_CONTROLLER.mdとdocs/FLEET_SCALING_PLAN.mdを参照してください。
• ネイティブプロンプト： 8種類のパラメーター化されたUniFi運用ワークフロー（ヘルスチェック、クライアント接続、Wi-Fiパフォーマンス、デバイス調査、ファイアウォールレビュー、変更計画、Protectの健全性、フリート概要）を、標準のprompts/listおよびprompts/get操作を通じて提供します。docs/PROMPTS.mdを参照してください。
• 安全性： 変更を行うすべてのツールでconfirm=Trueが必要で、dry_run=Trueもサポートします。さらに、読み取り専用モードとドライランのサーバーモード、リスクレベルに応じたロールベースのアクセス制御、ハッシュチェーン監査ログを備えています（下記を参照）。
• A2Aの検出と委任： 稼働中のツールレジストリから作成されるエージェントカードを/a2a/agent-cardおよび/.well-known/agent-card.jsonで提供します。また、機能マニフェストと、サーバー自身のロール、確認、監査制御のもとで登録済みツールを実行する委任エンドポイントも備えています。A2A.mdを参照してください。
• 可観測性： Prometheusの/metrics、/healthz、監査記録のSIEMエクスポート、オプションのRedisキャッシュ、HMAC検証付きWebhook。

APIモード

UNIFI_API_TYPEを設定して、サーバーがUniFiに接続する方法を選択します。

モード	接続先	用途
local（推奨）	LAN上のUniFiコンソールまたはゲートウェイ（UNIFI_LOCAL_HOST）	デバイスとクライアントの制御、設定、ファイアウォール、Protectなど、すべて
cloud-ea	UniFiのEarly AccessクラウドAPI	サイトと集計統計。デバイスごとの制御や設定には対応しません
cloud-v1	UniFiの安定版v1クラウドAPI	サイトと集計統計。デバイスごとの制御や設定には対応しません

クラウドツール（Site Manager、Mobility、InnerSpace、Carrier Fabric）はapi.ui.comを呼び出し、すべてのモードで登録されます。利用するにはUNIFI_SITE_MANAGER_ENABLED=trueを設定してください。localモードでは343個のツールが登録され、いずれかのクラウドモードでは71個が登録されます。

ゾーンベースのファイアウォールツールにはUniFi Network 9.0以降が必要です。ドキュメントに記載されているUniFiエンドポイントの一部は、すべてのファームウェアバージョンに存在するわけではありません。docs/UNIFI_API.mdを参照してください。

クイックスタート

1. APIキーを取得する

1. UniFi Site Managerにサインインします。
2. 設定 → Control Plane → Integrationsに移動し、Create API Keyを選択します。
3. キーをコピーします。キーが表示されるのは一度だけです。

2. インストールする

pip install unifi-mcp-server          # or: uv tool install unifi-mcp-server
# Fleet mode extras (Postgres, Redis):
pip install 'unifi-mcp-server[fleet]'

または、コンテナイメージを使用します（amd64、arm64、arm/v7対応。-fleetバリアントはamd64とarm64対応）。

docker pull ghcr.io/enuno/unifi-mcp-server:latest

3. MCP クライアントに追加する

Claude Desktop（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json）、Cursor（View: Open MCP Settings から mcp.json を開きます）、およびほとんどの他の MCP クライアントでは、同じ mcpServers ブロックを使用します。

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-mcp-server"],
      "env": {
        "UNIFI_API_KEY": "<your-api-key>",
        "UNIFI_API_TYPE": "local",
        "UNIFI_LOCAL_HOST": "192.168.2.1"
      }
    }
  }
}

pip でインストールした場合は、"command": "unifi-mcp-server" を使い、args は削除してください。代わりにコンテナを実行するには、次のようにします。

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "UNIFI_API_KEY=your-api-key-here",
        "-e", "UNIFI_API_TYPE=local",
        "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
        "ghcr.io/enuno/unifi-mcp-server:latest"
      ]
    }
  }
}

-i はそのままにし、-d は追加しないでください。クライアントはコンテナの標準入力と標準出力を介してサーバーと通信します。

4. 主な設定

変数	用途	デフォルト
UNIFI_API_KEY	UniFi API キー（必須）	—
UNIFI_API_TYPE	local、cloud-ea、または cloud-v1	cloud-ea
UNIFI_LOCAL_HOST / UNIFI_LOCAL_PORT	local モードでのコンソールアドレス	— / 443
UNIFI_LOCAL_VERIFY_SSL	コンソールの TLS 証明書を検証します。false にすると起動時に警告が記録されます	true
UNIFI_LOCAL_CA_FILE	自己署名コンソール用の CA 証明書（PEM）。検証を無効にする代わりに指定します	—
UNIFI_DEFAULT_SITE	ツール呼び出しでサイトが指定されていない場合に使用するサイト	default
UNIFI_SITE_MANAGER_ENABLED	クラウドツール（Site Manager、Mobility、InnerSpace、Carrier）を有効にします	false
UNIFI_PROFILE	ツールグループを1つだけ登録します（プロファイル）	すべて
UNIFI_READ_ONLY / UNIFI_DRY_RUN	読み取り専用、またはプレビュー専用のサーバーにします	false
DEBUG	debug_api_request（生の GET/DELETE、破壊的操作の階層。読み取り専用では削除されます）を登録します。本番環境では未設定のままにしてください	未設定
MCP_SERVER_TRANSPORT	stdio、streamable_http、http、または sse	stdio
MCP_AUTH_TOKEN	ネットワークトランスポートでは必須の Bearer トークンです。viewer:<token>（または operator:、admin:）を指定すると、トークンのロールが制限されます	—
REDIS_URL	任意のレスポンスキャッシュ	—
WEBHOOK_SECRET	UniFi ウェブフック受信用の HMAC シークレット	—
DATABASE_URL	フリートモード（Postgres）を有効にします	—

.env.example には、監査ログ、SIEM エクスポート、メトリクス、Supermemory、agnost.ai を含む、すべての設定がコメント付きで記載されています。

エージェントスキル

skills/ ディレクトリにはエージェントスキルが含まれています。これは、AI エージェントが必要に応じて読み込む Markdown ファイルで、すべてのツール定義をコンテキストに保持せずに、利用可能な UniFi ツールと安全な使用方法を把握できます。各スキルは SKILL.md を含むフォルダーで、Claude Code やその他のエージェントがインストールする形式になっています。

サーバーの使用（オペレータースキル）

スキル	内容
unifi-network	クライアント、ネットワークと VLAN、WiFi、DHCP、DNS、WAN、バウチャー
unifi-devices	インベントリ、採用、再起動とアップグレード、ポート、スイッチング、トポロジ
unifi-security	ファイアウォールルールとグループ、ゾーンベースファイアウォール、ACL、ポートフォワーディング、VPN
unifi-system	サイト、バックアップ、QoS、トラフィックフロー、DPI、RADIUS、ゲストポータル
unifi-channel-planning	周辺スキャンに基づく、干渉の少ない WiFi チャネルプラン

このコードベースの変更（開発者スキル）

スキル	内容
unifi-mcp-tool-builder	MCP ツールの追加全般：モデル、関数、登録、テスト、ドキュメント
unifi-network-config-tools	ネットワーク設定ツール：URL の名前空間、サイト ID、読み取り・変更・書き込み
unifi-security-tools	ファイアウォール、ZBF、ACL、ポートフォワードのツールとリスク階層
unifi-protect-tools	protect_* モジュールと Protect クライアント
unifi-cloud-fleet-tools	クラウド API ツールとフリートスタック

インストール

Claude Code は、~/.claude/skills/<name>/SKILL.md（すべてのセッション）または <project>/.claude/skills/<name>/SKILL.md（1 つのプロジェクト）からスキルを読み込みます。使用するフォルダーをコピーします。

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
mkdir -p ~/.claude/skills

# All operator skills
cp -r skills/unifi-network skills/unifi-devices skills/unifi-security \
      skills/unifi-system skills/unifi-channel-planning ~/.claude/skills/

# Or one skill
cp -r skills/unifi-security ~/.claude/skills/

# The one-file overview of the whole server, as a skill named "unifi"
mkdir -p ~/.claude/skills/unifi && cp SKILL.md ~/.claude/skills/unifi/SKILL.md

同じ SKILL.md 形式を読み取るほかのエージェントも同じフォルダーを使用します。該当するエージェントのスキルディレクトリにコピーしてください（たとえば、Codex は .agents/skills/ を読み込みます）。更新するには、再度プルしてコピーします。このリポジトリ内では、開発者向けスキルはすでに Claude Code（.claude/skills/）と Codex（.agents/skills/）にインストールされています。

使用方法

スキルを自分で呼び出す必要はありません。エージェントが各スキルの説明を読み、リクエストに一致するスキルを読み込んで、そのスキルが説明する MCP ツールを呼び出します。そのため、MCP サーバーも同じクライアントで設定しておく必要があります。たとえば、次のようになります。

• 「現在、ゲスト VLAN にいるクライアントはどれですか？」と尋ねると、unifi-network が読み込まれます。
• 「ゾーンベースファイアウォールを監査して、WAN から LAN への通信を許可する設定がないか確認してください。」と尋ねると、unifi-security が読み込まれます。
• 「近隣の AP と 5 GHz チャンネルを共有している AP はどれですか？ チャンネルプランを提案してください。」と尋ねると、unifi-channel-planning が読み込まれます。

エージェントがスキルを選ばない場合は、名前を指定してください（「unifi-security スキルを使ってください」）。対応する UNIFI_PROFILE とスキルを組み合わせると、ツールの一覧も少なくできます。詳しいガイドは docs/SKILLS.md を参照してください。

ツールプロファイルと安全制御

プロファイル。 UNIFI_PROFILE ではモジュールのグループを 1 つだけ登録するため、クライアントに表示されるツール定義が少なくなります。

プロファイル	ツール	対象
network	48	クライアント、ネットワーク、WiFi、DHCP、DNS、WAN、バウチャー、チャンネルプランニング
devices	53	デバイス、コントロール、移行、ポート、スイッチング、トポロジー、診断
security	47	ファイアウォール、ZBF、ACL、ポートフォワーディング、VPN、コンテンツフィルタリング
system	182	サイト、バックアップ、イベント、DPI、QoS、RADIUS、トラフィックフロー、Protect、クラウド
protect	75	Protect モジュール
mobility / innerspace / carrier	12 / 10 / 15	各 1 つのクラウド API
minimal	19	サイト、クライアント、デバイス

各プロファイルには、共通の 4 つのフリートツールも含まれています。不明なプロファイルを指定すると、警告がログに記録され、すべてのツールが読み込まれます。

安全制御。

• 変更を行う各ツールでは confirm=True が必須です。また、dry_run=True を指定すると、変更を実行せずに内容を返します。
• UNIFI_READ_ONLY=true を設定すると、変更を行うツールはツール一覧から完全に除外されます。UNIFI_DRY_RUN=true を設定すると、変更を行うすべての呼び出しがプレビューモードになります。
• DEBUG=true を設定すると、任意のコントローラーエンドポイントに対する未加工の GET または DELETE を行う debug_api_request が追加されます。これは破壊的操作の階層に属するツールです。DELETE には confirm=True が必要で、読み取り専用モードでは除外されます。本番環境では DEBUG を未設定のままにしてください。
• トークンを使用する場合、各ツールにはリスク階層（read、write、destructive）があり、各ロールには使用できる階層が割り当てられます。viewer は読み取り、operator は書き込みができ、admin は削除、復元、再起動、クライアントのブロック、ファイアウォールポリシーの変更など、破壊的な操作も実行できます。API.md を参照してください。
• 変更内容は、ハッシュチェーン付きの JSON Lines 監査ログ（フリートモードでは Postgres）に記録されます。フィールド暗号化と SIEM エクスポートも任意で利用できます。SECURITY.md を参照してください。
• 入力は Pydantic で検証され、認証情報はログからマスキングされます。

ネットワークトランスポートとデプロイ

stdio はデフォルトで、ポートは不要です。ネットワーク経由で MCP を提供するには、Streamable HTTP を使用します。

export MCP_SERVER_TRANSPORT=streamable_http
export MCP_SERVER_PORT=3000
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)   # required on every network transport
unifi-mcp-server
# Listening on 127.0.0.1:3000; clients send Authorization: Bearer $MCP_AUTH_TOKEN

クライアントと MCP ゲートウェイは、http://<host>:3000/mcp に接続します。サーバーは、MCP_SERVER_HOST を設定しない限り 127.0.0.1 にバインドされます。さらに外部へ公開する前に、認証機能を備えた TLS プロキシを前段に配置してください。http も使用できます。sse は非推奨です。mcp-remote などのクライアントプロキシでは、初期化ハンドシェイクが競合することがあります（#96）。

公開ポートをループバックにバインドしたコンテナの場合：

services:
  unifi-mcp:
    image: ghcr.io/enuno/unifi-mcp-server:latest
    environment:
      UNIFI_API_KEY: your-api-key
      UNIFI_API_TYPE: local
      UNIFI_LOCAL_HOST: 192.168.2.1
      MCP_SERVER_TRANSPORT: streamable_http
      MCP_SERVER_PORT: 3000
      MCP_SERVER_HOST: 0.0.0.0          # inside the container only
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
    ports:
      - "127.0.0.1:3000:3000"

リポジトリの docker-compose.yml は、Redis と MCP Toolbox ダッシュボード（MCP_TOOLBOX.md）を追加します。.env.docker.example を .env にコピーし、make compose-up を実行してください。この設定例は、読み取り専用（UNIFI_READ_ONLY=true）で、viewer の stdio 呼び出し元（UNIFI_STDIO_ROLE=viewer）として起動します。変更を許可するには、UNIFI_READ_ONLY=false に設定し、UNIFI_STDIO_ROLE を operator に引き上げてください。破壊的な変更を許可する場合は admin に設定します。

• Ansible： deploy/ansible/ を使って、サーバー単体、単一ホストのフリート（サーバー、ワーカー、Redis、Postgres）、または複数ホスト上の nginx の背後にあるレプリカをデプロイできます。AI エージェントにデプロイを実行させる場合は、docs/deploy-prompts/ のプロンプトから始めてください。
• Kubernetes： deploy/helm/unifi-mcp/ は、サーバー単体、またはワーカーを含むフリートモードで使える Helm チャートです。すべての認証情報は、既存の Secret から取得します。

コードからサーバーを呼び出す

どの MCP クライアントライブラリでも使用できます。FastMCP クライアントを使う場合：

import asyncio

from fastmcp import Client

config = {
    "mcpServers": {
        "unifi": {
            "command": "unifi-mcp-server",
            "env": {
                "UNIFI_API_KEY": "<your-api-key>",
                "UNIFI_API_TYPE": "local",
                "UNIFI_LOCAL_HOST": "192.168.2.1",
            },
        }
    }
}


async def main() -> None:
    async with Client(config) as client:
        sites = await client.call_tool("list_sites", {})
        print(sites.data)

        clients = await client.call_tool("list_active_clients", {"site_id": "default"})
        print(clients.data)

        # Mutations need confirm=True; dry_run=True previews the change.
        preview = await client.call_tool(
            "create_firewall_zone",
            {"site_id": "default", "name": "IoT", "confirm": True, "dry_run": True},
        )
        print(preview.data)


asyncio.run(main())

bin/unifi-cli は、シェルから単一のツールを実行します（unifi-cli list-clients --site default）。docs/SKILLS.md を参照してください。

ネイティブ MCP プロンプト

ツールに加えて、サーバーは標準の MCP プロンプトインターフェースを通じて、パラメーター化された 8 つの UniFi 運用ワークフローを公開します。クライアントは prompts/list でそれらを検出し、prompts/get でレンダリング済みのワークフロー概要を取得します。

import asyncio

from fastmcp import Client

config = {
    "mcpServers": {
        "unifi": {
            "command": "unifi-mcp-server",
            "env": {
                "UNIFI_API_KEY": "<your-api-key>",
                "UNIFI_API_TYPE": "local",
                "UNIFI_LOCAL_HOST": "192.168.2.1",
            },
        }
    }
}


async def main() -> None:
    async with Client(config) as client:
        for prompt in await client.list_prompts():
            print(prompt.name, prompt.description)

        result = await client.get_prompt(
            "network_health_check",
            {"site_id": "default", "focus": "wan"},
        )
        for message in result.messages:
            print(message.content.text)


asyncio.run(main())

プロンプトは network_health_check、troubleshoot_client_connectivity、 troubleshoot_wifi_performance、investigate_device、 review_firewall_policy、plan_network_change、protect_health_check、 fleet_health_summary です。ワークフローに必要なツールがこのサーバーに登録されている場合にのみ、そのワークフローが公開されます。そのため、プロンプトの一覧は API モード、プロファイル、読み取り専用設定、ドライラン設定に応じて変わります。

プロンプトを取得しても、ワークフローは実行されず、承認も付与されません。レンダリングされたテキストは、エージェントが呼び出すべき読み取りツールと報告すべき内容を示します。エージェント自身がツールを呼び出し、サーバーのロールチェック、confirm ゲート、監査証跡は引き続き適用されます。

make inspect を使って MCP Inspector を開き、プロンプトを確認するか、MCPJungle CLI でゲートウェイが転送する内容を確認してください。

mcpjungle list prompts --server unifi
mcpjungle get prompt unifi__network_health_check --arg site_id=default

ツールのみを扱うクライアントにはプロンプトが表示されません。これはクライアント側の制限です。プロンプトをツールとして扱う shim はありません。

全カタログ、利用可能性マトリックス、検証ルール、手動受け入れ手順については、docs/PROMPTS.md を参照してください。

ドキュメント

ドキュメント	内容
API.md	すべての MCP ツールとリソースのパラメーターおよび例
docs/PROMPTS.md	ネイティブ MCP プロンプトのカタログ、引数、利用可能条件
A2A.md	エージェントカード、機能マニフェスト、委任エンドポイント
docs/AUDIT_A2A_SKILLS.md	A2A とスキルの監査：実装済みのもの、未実装のもの、その理由
docs/SKILLS.md	エージェントのスキル、プロファイル、CLI ラッパー
docs/UNIFI_API.md	ツールが利用する UniFi エンドポイント
MULTI_CONTROLLER.md	フリートモード：コントローラー、トークン、ロール
METRICS.md、WEBHOOK_SETUP.md、A2A.md	メトリクス、Webhook、A2A エージェントのエンドポイント
NETWORK_PLAYBOOK.md、HARBOR_SETUP.md	運用手順書
SECURITY.md	脆弱性の報告、監査ログ、セキュリティ強化
SPEC.md、DEVELOPMENT_PLAN.md、ROADMAP.md	アーキテクチャの目標とロードマップ
CHANGELOG.md、docs/RELEASE_PROCESS.md	リリース履歴、リリースの作成と公開方法

開発

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
make install    # uv sync from uv.lock with the dev extra (no activation needed)
make hooks      # pre-commit and commit-msg hooks
cp .env.example .env   # then set UNIFI_API_KEY and, for local mode, UNIFI_LOCAL_HOST

make test       # unit tests
make ci         # every blocking CI check: lint, typecheck, security, docs coverage, tests with the 80% gate
make inspect    # open the server in the MCP Inspector (needs Node.js)
make help       # list every target

make を使わない場合も、同じコマンドを uv run --locked で実行できます。たとえば uv run --locked pytest tests/unit/ -m "not integration" です。統合テスト（-m integration）には実際の UniFi ハードウェアが必要です。

構成：src/main.py がサーバーを構築し、src/tools/ にツールモジュール、src/api/ に UniFi クライアント、src/models/ に Pydantic モデル、src/fleet/ にフリートスタック、tests/unit/ にユニットテストがあります。AGENTS.md と CLAUDE.md では規約を詳しく説明し、commands.md では開発コマンドを一覧にしています。

コントリビュート

人間や AI コーディングエージェントからのコントリビューションを歓迎します。CONTRIBUTING.md と AGENTS.md をご覧ください。

1. リポジトリをフォークして、ブランチを作成します。
2. まずテストを作成し、新しいコードのカバレッジを 80% 以上に保ち、make ci を実行します。
3. Conventional Commits 形式のコミットメッセージ（feat: ...、fix: ...）を使用し、プルリクエストを作成します。

タイトルに [Bug] を含む Issue がメンテナーまたはコラボレーターによって作成された場合、自動で初回分析が行われます。それ以外の報告は手動でトリアージされます（詳細）。

セキュリティ

脆弱性は SECURITY.md の説明に従って報告してください。認証情報をコミットしないでください。

謝辞

• sirkirby/unifi-network-mcp、参考実装
• MakeWithData の UniFi MCP ガイド
• Model Context Protocol と FastMCP

ライセンス

Apache License 2.0。LICENSE をご覧ください。

リンク

• Issue とディスカッション：GitHub Issues、GitHub Discussions
• リリース：https://github.com/enuno/unifi-mcp-server/releases
• PyPI：https://pypi.org/project/unifi-mcp-server/
• コンテナイメージ：https://ghcr.io/enuno/unifi-mcp-server
• MCP Registry：https://registry.modelcontextprotocol.io で io.github.enuno/unifi-mcp-server を検索してください