unifi-mcp

Example Corp / examplecorp の UniFi フリート を、公式 UniFi Site Manager API（api.ui.com）経由で Claude カスタムコネクタとして公開する、読み取り専用のリモート MCP サーバーです。

odoo-ticket-mcp や TRMM MCP サーバーの兄弟プロジェクトで、同じアーキテクチャを採用しています。

Claude (claude.ai / Claude Code)
   │  OAuth 2.0 bearer token (Microsoft Entra ID)
   ▼
nginx  — TLS, Anthropic egress-IP allowlist (160.79.104.0/21), 403 otherwise
   │  http://127.0.0.1:8097
   ▼
unifi-mcp container (Portainer stack, FastMCP 3.x, Streamable HTTP at /mcp)
   │  X-API-KEY (Site Manager API key, read-only usage)
   ▼
api.ui.com  — Site Manager API + connector proxy into each console's Network API

• クライアント→サーバー認証: Microsoft Entra ID（リソースサーバーモード）。サーバーは audience に紐付いたベアラートークンを検証するのみで、トークンを発行することはありません。アクセス制御は、アプリ登録の Entra グループメンバーシップによって行われます。

• サーバー→UniFi 認証: 固定の Site Manager API キーを1つ使用します（unifi.ui.com → API キー で、Site Manager アプリケーションスコープ + Network アプリケーションスコープ、全サイトを選択して作成）。v1 では、呼び出し元の ID は意図的に UniFi に転送されません。

• ネットワークパス: パブリック DNS → nginx（TLS + Anthropic IP 許可リスト）→ コンテナ。多層防御として、許可リストは OAuth に追加して適用されます。

ツール（すべて読み取り専用）

Site Manager（フリート全体）:

コネクタプロキシ（コンソール単位のドリルダウン。VPN は不要）:

一般的なフロー: unifi_list_hosts → コンソールを選択 → unifi_network_sites → unifi_network_clients / unifi_network_device

Related MCP server: UniFi MCP Server

ローカル開発

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
copy .env.example .env    # fill in UNIFI_API_KEY; set MCP_AUTH_ENABLED=false
.venv\Scripts\python -m unifi_mcp
# → http://127.0.0.1:8000/mcp  (test with MCP Inspector)

MCP_AUTH_ENABLED=false でエンドポイントが開きます。ローカルテスト専用で、本番環境では使用しないでください。

Entra ID アプリ登録（初回のみ）

注釈付きのバージョンは TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md を参照してください。概要は以下の通りです。この順番で行ってください:

1. アプリの登録 → 新規登録 — 名前は UniFi MCP、サポートされるアカウントの種類はシングルテナント、リダイレクト URI はまだ指定しません。クライアント ID とテナント ID をコピーします。

2. API の公開 → アプリケーション ID URI — 正確に https://unifi-mcp.example.com/mcp に設定します（AADSTS9010010 を防ぎます）。

3. API の公開 → スコープの追加 — access_as_user を追加し、管理者とユーザーの同意が可能な状態にします。

4. 証明書とシークレット → 新しいクライアント シークレット — claude-connector、有効期限は 24 か月。すぐに値をコピーします。

5. 認証 → プラットフォームを追加 → Web — リダイレクト URI に https://claude.ai/api/mcp/auth_callback と https://claude.com/api/mcp/auth_callback を追加します。

6. マニフェスト — requestedAccessTokenVersion を 2 に設定します（発行者不一致の 401 エラーを防ぎます）。

7. エンタープライズ アプリケーション → UniFi MCP → プロパティ — 割り当てが必要 = はい に設定します。

8. エンタープライズ アプリケーション → ユーザーとグループ — Unifi-MCP-Users グループを追加します。グループメンバーシップ = コネクタを使用できるユーザーです。

デプロイ

PORTAINER_DEPLOY.md（Portainer Git スタック + Webhook 再デプロイ）と deploy/nginx-unifi-mcp.conf（TLS + Anthropic IP 許可リスト）を参照してください。

claude.ai にコネクタを登録

設定 → コネクタ → カスタムコネクタを追加:

受け入れテスト

# 1. Discovery doc advertises the full resource scope (not api://…)
curl -s https://unifi-mcp.example.com/.well-known/oauth-protected-resource/mcp | jq .scopes_supported

# 2. Unauthenticated /mcp is challenged
curl -i https://unifi-mcp.example.com/mcp        # 401 + WWW-Authenticate: Bearer

# 3. Non-Anthropic source IP is blocked at nginx
curl -i https://unifi-mcp.example.com/mcp        # from anywhere else: 403

# 4. Health (host-local, bypasses nginx)
curl http://<docker-host>:8097/healthz                 # {"status":"ok","service":"unifi_mcp"}

# 5. In claude.ai: connect as a Unifi-MCP-Users member → tools appear;
#    non-member → AADSTS50105 at sign-in.