unifi-mcp

Только для чтения удалённый MCP-сервер, предоставляющий парк устройств UniFi Example Corp / examplecorp в качестве пользовательского коннектора Claude через официальный UniFi Site Manager API (api.ui.com).

Родственный проект odoo-ticket-mcp и MCP-серверов TRMM — та же архитектура:

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, режим ресурсного сервера. Сервер проверяет bearer-токены, привязанные к аудитории; он никогда их не выдаёт. Доступ контролируется членством в группах Entra в регистрации приложения.

• Аутентификация сервер → UniFi: один фиксированный ключ API Site Manager (созданный на unifi.ui.com → API Keys с областями приложения Site Manager и Network, все сайты). Идентичность вызывающего намеренно НЕ передаётся в UniFi в v1.

• Сетевой путь: публичный DNS → nginx (TLS + список разрешённых IP-адресов Anthropic) → контейнер. Защита в глубину: allowlist дополняет 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 перенаправления. Скопируйте идентификатор клиента и идентификатор арендатора.

2. Открыть API → URI идентификатора приложения — установите точно https://unifi-mcp.example.com/mcp (предотвращает AADSTS9010010).

3. Открыть API → Добавить область — установите access_as_user, администраторы и пользователи могут давать согласие, включено.

4. Сертификаты и секреты → Новый секрет клиента — claude-connector, 24 месяца. Скопируйте значение сразу.

5. Аутентификация → Добавить платформу → Веб — 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 + список разрешённых IP-адресов Anthropic).

Регистрация коннектора в 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.