API VEGA

mcp-unifi

Безопасность в первую очередь: сервер MCP для автономного UniFi. Превью в режиме dry-run, аудит в формате JSONL, композиционная отмена изменений. Сеть + Protect + Access.

Сервер MCP, построенный вокруг идеи, что вызовы инфраструктуры под управлением LLM требуют защитных механизмов. Каждый деструктивный инструмент принимает dry_run=True и возвращает предсказанный набор изменений без применения. Композитивные инструменты (create_iot_network, create_guest_network, provision_homelab_service, provision_camera) сохраняют предыдущее состояние и откатывают выполненные шаги при частичной неудаче. Каждый вызов — в режиме dry-run или реальном — попадает в аудит-лог в формате JSONL с удалёнными секретами; входящая в комплект CLI mcp-unifi-replay может повторно выполнить лог на новом контроллере.

Помимо базовой подложки безопасности: инструменты Network для устройств, настройки радиосигналов AP, VLAN, WLAN, файрвола, портов коммутатора, переадресаций портов, DHCP-резервирования, групп AP, наблюдения, Threat Management / IDS-IPS, Honeypot и Teleport VPN, а также опциональные модули Protect (камеры, события движения, умные детекции, настройки записи) и Access (двери, учетные данные, посетители, события бейджей, узлы / считыватели). Каждый инструмент принимает параметр controller, чтобы один экземпляр сервера управлял несколькими сайтами UniFi. Поддерживает и stdio (Claude Desktop, uvx, .dxt) и Streamable HTTP (Docker, Helm). Полный, актуальный перечень инструментов — в автоматически сгенерированном Манифесте инструментов. Работает на любом шлюзе UniFi OS с UniFi Network 9.x или выше (UDM, UDM Pro, UDM SE, UCG-Fiber, UCG-Ultra, UDR, UDW, UniFi OS Server), аутентификация через локальный API-ключ из Settings → Control Plane → Integrations. Проверено для UCG-Fiber fw 5.1.12.33296. Не требуется Site Manager или облачный аккаунт.

Установка

Четыре поддерживаемых пути. Выберите тот, что соответствует вашему способу запуска Claude.

Docker

Долгоживущий контейнер, Streamable HTTP на порту 3714. Лучше всего подходит для хомелаба и многоклиентских сценариев.

HTTP-транспорт не запустится без токена bearer, поэтому необходимо указать его:

export MCP_UNIFI_TOKEN=$(openssl rand -hex 32)
docker run --rm -p 3714:3714 \
  -e STUB_MODE=true \
  -e MCP_UNIFI_AUTH_TOKENS="$MCP_UNIFI_TOKEN" \
  ghcr.io/pete-builds/mcp-unifi:latest

Клиенты затем отправляют заголовок Authorization: Bearer $MCP_UNIFI_TOKEN. Для разовой локальной проверки по loopback-устройству можно отключить аутентификацию altogether, используя:

-e MCP_UNIFI_AUTH_REQUIRED=false

но не применяйте это на интерфейсе, доступном из внешних сетей — каждый подключенный клиент получит доступ с правами администратора к контроллеру.

Claude Desktop (.dxt) — установка одним кликом

Скачайте mcp-unifi-<version>.dxt с последнего релиза и дважды щёлкните. Конфигурация осуществляется через встроенный UI в Claude Desktop. В дистрибутив включён окружение Python; отдельной установки не требуется. Использует транспорт via stdio.

Helm

helm repo add mcp-unifi https://pete-builds.github.io/mcp-unifi/
helm install unifi mcp-unifi/mcp-unifi \
  --set unifi.host=192.168.1.1 \
  --set unifi.apiKey=<your-local-api-key> \
  --set auth.tokens=$(openssl rand -hex 32)

Чарт разворачивает auth.required: true с auth.tokens: "", поэтому под не запустится, пока не будет установлен токен (или используйте --set auth.required=false, что допустимо только для доверенного одноарендного кластера).

uvx / pipx

Быстрый запуск напрямую из GitHub-репозитория. Используется stdio.

uvx --from git+https://github.com/pete-builds/mcp-unifi mcp-unifi

Укажите конкретный релиз, добавив @v0.5.0-rc.2 (или любой тег) к URL.

Полные руководства по каждому пути установки доступны на сайте документации.

Архитектура

  • Безопасность как базис. Каждый деструктивный инструмент принимает dry_run=True и возвращает ожидаемые изменения без записи. Композитные инструменты (create_iot_network, create_guest_network, provision_homelab_service, provision_camera) фиксируют предыдущее состояние и откатывают шаги при частичной ошибке. Каждый вызов инструмента попадает в аудит-лог JSONL с удалёнными секретами; утилита mcp-unifi-replay может воспроизвести лог на чистом контроллере.

  • Единое изображение, множество контроллеров. Один контейнер управляет модулями Network, Protect и Access вместе. Один и тот же процесс может управлять несколькими сайтами UniFi параллельно через параметр controller и YAML-файл контроллеров (MCP_UNIFI_CONTROLLERS_FILE). Нет необходимости запускать отдельный процесс на каждый контроллер.

  • Аутентификация по API-ключу в первую очередь. Используется локальный API-ключ из Settings → Control Plane → Integrations против эндпойнта /proxy/network/api. Без хранения имени пользователя/пароля, без облачного аккаунта, без зависимости Site Manager.

  • Мульти-канальная дистрибуция. Docker, одноразовая установка для Claude Desktop (.dxt), Helm-чарт, uvx. Значится в официальном MCP Registry. Контейнерные образы подписаны cosign (keyless OIDC) и к каждому релизу прикреплен SBOM CycloneDX.

  • Сеть + Protect + Access. По умолчанию включён Network; Protect и Access можно включить через MCP_UNIFI_MODULES_ENABLED=network,protect,access. Access поставляется с чтением данных (разблокировку дверей и выдачу учётных данных необходимо авторизовать сессией и это откладывается). UniFi Drive не входит в область проекта.

Быстрый старт

Самый быстрый холодный старт: Docker + Claude Code в режиме stub, оборудование не требуется.

Запустите контейнер. Аутентификация включена по умолчанию, поэтому сначала получите токен:

export MCP_UNIFI_TOKEN=$(openssl rand -hex 32)
docker run -d --rm -p 3714:3714 \
  -e STUB_MODE=true \
  -e MCP_UNIFI_AUTH_TOKENS="$MCP_UNIFI_TOKEN" \
  --name mcp-unifi ghcr.io/pete-builds/mcp-unifi:latest

Зарегистрируйте его в Claude Code, передав токен:

claude mcp add --transport http --scope user unifi http://localhost:3714/mcp \
  --header "Authorization: Bearer $MCP_UNIFI_TOKEN"

Проверьте соединение:

claude mcp list

В сессии Claude Code попросите: «показать мои UniFi-устройства». Вы получите два подставочных устройства.

Когда будете готовы указывать реальный шлюз, отключите режим stub:

docker run -d --rm -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  -e MCP_UNIFI_AUTH_TOKENS="$MCP_UNIFI_TOKEN" \
  --name mcp-unifi ghcr.io/pete-builds/mcp-unifi:latest

Сгенерируйте API-ключ на шлюзе UniFi: Settings → Control Plane → Integrations → Create API Key.

Конфигурация

Вся конфигурация считывается из переменных окружения (и из файла .env, если он присутствует). Пять самых частых вариантов:

ПеременнаяПо умолчаниюПримечания
STUB_MODEtrueКогда значение false, требуется конфигурация контроллера в реальном режиме.
UNIFI_HOST(пусто)IP-адрес или имя хоста шлюза. Требуется в реальном режиме.
UNIFI_API_KEY(пусто)Локальный API-ключ. Требуется в реальном режиме.
MCP_UNIFI_MODULES_ENABLEDnetworkУстановите network,protect,access, чтобы включить все три модуля.
MCP_UNIFI_CONTROLLERS_FILE(unset)YAML-файл с именованными контроллерами для мультисайтов.

Полную справку по переменным окружения и схему YAML для мульти-сайтов смотрите в Документации по конфигурации.

Как это построено

Инженерная обвязка вокруг интерфейса инструмента (см. Манифест инструментов для актуального счёта) — для тех, кто хочет понять, чем всё держится:

Тестовая дисциплина. Около 880 тестов на юнит-тестирование, интеграцию и свойств-проверку (Hypothesis) — смотрите pytest --collect-only для актуального счётчика. HTTP-модель тестируется с помощью respx, чтобы тесты не обращались к реальному контроллеру. Покрытие ветвлений в CI держится на уровне не менее 90% (минимум — 90%).

Качество кода. Проверки качества через Ruff (pycodestyle, pyflakes, isort, flake8-bugbear, pyupgrade, simplify, flake8-bandit и пр.), строгий mypy (без неявного Any, пометки недостижимого кода, флаги по игнорированиям). Прежневыполненные хуки вызывают lint, форматирование, типы и регенерацию манифеста инструмента с проверкой на соответствие. Bad-код не допускается в CI.

CI-пайплайн (5 гейтов). Каждый PR проходит дрейф зависимости lockfile → линт + типизация → тесты + покрытие → сборка multi-arch Docker → сканирование Trivy файловой системы и образа (HIGH/CRITICAL проваливают сборку). Каждый этап блокирует следующий.

Пайплайн релизов. Тег vX.Y.Z триггерит мульти-арх Docker-сборку, подписание cosign без ключей через sigstore OIDC, аттестацию происхождения сборки SLSA, SBOM CycloneDX через Syft прикреплён к релизу на GitHub, дистрибутив .dxt для Claude Desktop, загрузку GHCR с тегами vX.Y.Z, X.Y и latest, а также авто-увеличение примера docker-compose.yml в main.

Гигиена зависимостей. Пиннинг через pip install --require-hashes. Специальный шаг CI проверяет соответствие каждой закодированной зависимости в requirements.in и requirements.lock, чтобы никто не мог подтянуть несовместимые версии. Dependabot автоматически принимает безопасные патчи. База образов — дайджест-подпись, не тег-подпись.

Укрепление контейнеров. Работает как не‑root пользователь 1000, без оболочки, без домашнего каталога. Фиксированная файловая система только для чтения через Docker / Helm. /tmp — tmpfs объёмом 16MiB. Установлен no-new-privileges. Все Linux capabilities сняты. Специальный эндпойнт /health обеспечивает отсутствие шума 406 на каждом healthcheck-диспетчере.

Безопасность. Bearer-токен аутентификации на HTTP-т transport, безопасно по умолчанию (запуск без токена запрещён). Аудит-лог фиксирует каждый аутентифицированный client_id в вызове с удалением секретов внутри api_key, passphrase, password, secret, token при совпадении подстрок. API-ключи обёрнуты в pydantic SecretStr. В SECURITY.md прописан приватный путь раскрытия уязвимостей.

Распространение. GHCR (мультиарх), Smithery (зарегистрировано), MCP Registry (перечислено), Helm-чарт (Templates для Secret/Deployment/Service/Ingress/NetworkPolicy), .dxt-бандл, uvx / pipx.

Документация. Astro Starlight автоматически разворачивается на GitHub Pages. Страницы справочников по инструментам формируются из интеграции FastMCP через scripts/generate_tool_manifest.py, а pre-commit регенерирует и проверяет соответствие между кодом и документацией, чтобы они не расходились. CHANGELOG ведётся по формату Keep a Changelog.

Версионирование. pyproject.toml, тег в Git, запись в CHANGELOG, тег Docker-образа, образец docker-compose и версия в Helm-чарте appVersion остаются согласованными. Разработчики не допускают расхождение между документами и кодом по версии.

Разработка

Клонируйте репозиторий, установите зависимости для разработки и активируйте препроцессоры кряков:

git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" pre-commit
pre-commit install

Препроцессоры выполняют Ruff (lint + форматирование), strict-модификацию mypy и генератор манифеста инструментов. Манифест-хук регенерирует

docs/site/src/content/docs/tools/ при изменении любого файла в

src/mcp_unifi/modules/ и вызывает отклонение коммита, если на диске манифест не соответствует зарегистрированному набору инструментов. Запускайте тесты командой:

pytest.

Чтобы вручную регенерировать манифест:

python scripts/generate_tool_manifest.py        # запись
python scripts/generate_tool_manifest.py --check  # drift-check CI-стиля

Документация

Лицензия

MIT.