UniFi MCP Server

mcp-name: io.github.mikeholownych/unifi-mcp

MCP-сервер (Model Context Protocol), который предоставляет ИИ-ассистентам, таким как Claude, доступ к возможностям управления и анализа инфраструктуры UniFi Network и Protect.

Благодарности: Этот проект начинался как форк gbassaragh/Unifi-mcp и с тех пор превратился в полностью независимый проект. Спасибо @gbassaragh за отличную отправную точку.

Улучшения относительно исходного проекта

• Исправлена маршрутизация аутентификации локальной сессии — в UNIFI_MODE=local запросы теперь корректно используют традиционный API контроллера (/proxy/network) с сессионной аутентификацией через cookie + CSRF. Исходный проект всегда направлял запросы через Integration API независимо от режима.

• Разрешение базового URL с учётом режима — api_base_url теперь учитывает настроенный режим аутентификации, а не безусловно возвращает конечную точку Integration API.

• Расширенный набор тестов — 57 проходящих тестов, покрывающих конфигурацию, поведение сетевого клиента, регистрацию инструментов сервера и интеграции Protect.

Related MCP server: UniFi MCP Server

Возможности

UniFi Network

• Управление устройствами: просмотр, перезагрузка, поиск и обновление устройств UniFi (точки доступа, коммутаторы, маршрутизаторы)

• Управление клиентами: мониторинг подключённых клиентов, блокировка/разблокировка, просмотр статистики трафика

• Управление сайтами: просмотр состояния сайта, сетевых конфигураций, VLAN и настроек Wi-Fi

• Статистика и мониторинг: события, тревоги, тесты скорости и статистика DPI

• Аналитика на базе ИИ: анализ сети, рекомендации по оптимизации и устранение неполадок

UniFi Protect

• Управление камерами: список камер, просмотр статуса, получение живых снимков

• Мониторинг системы: статус NVR, сводка по состоянию камер

• Аксессуары: управление освещением, датчиками, звонками и устройствами просмотра

• Liveviews: доступ к настроенным макетам просмотра камер

Поддержка нескольких устройств

• Настройка нескольких устройств UniFi (шлюзы, NVR и т. д.)

• Выбор конкретных устройств по имени — все инструменты сети и Protect принимают необязательный параметр device

• Индивидуальные API-ключи: каждое настроенное устройство аутентифицируется собственным ключом

• Смешение сервисов Network и Protect на разных устройствах

Режимы аутентификации

При использовании API-ключей (Integration API) часть функций контроллера доступна только через устаревшую сессионную аутентификацию (UNIFI_MODE=local): сетевые события, тревоги, статистика DPI, тесты скорости, конфигурации WLAN, правила брандмауэра, профили портов и таблицы маршрутизации. Инструменты для этих функций возвращают понятную ошибку с объяснением, как их включить, а не завершаются молча. Инструменты аналитики корректно деградируют и сообщают об ограничениях данных.

Примечание о локальных учётных записях: администраторы SSO/учётных записей Ubiquiti, защищённые MFA, не могут завершить вход по сессии. Создайте локального администратора на своей консоли (Restrict to Local Access Only) для UNIFI_MODE=local.

Навыки агента

Встроенные навыки (в skills/) обучают агентов проверенным рабочим процессам для этого сервера, включая характерные для контроллера подводные камни (удалённые конечные точки Network 10, правила пар зон, переход WPA3).

Полная документация: руководство по использованию, ожидаемые результаты, устранение неполадок и запрос новых функций — см. SKILLS.md.

Краткий справочник

Как работают навыки

Просто опишите свою проблему естественным языком — агент подберёт подходящий навык и будет следовать его рабочему процессу:

• «У меня не работает интернет» → unifi-internet-down диагностирует WAN, модем и шлюз

• «Кто в моём Wi-Fi?» → unifi-whos-home показывает список устройств и помечает неизвестные

• «Проверь мою сеть» → unifi-network-audit формирует полный отчёт о состоянии

• «Настрой мой новый телевизор» → unifi-setup-new-device помогает с подключением к Wi-Fi

Write-gated навыки (отмечены выше) вносят изменения в вашу сеть — перед применением изменений они всегда запрашивают подтверждение.

Навыки для нетехнических пользователей избегают жаргона, объясняют каждый технический термин и требуют подтверждения перед потенциально опасными действиями.

Установка (для проекта): скопируйте в .claude/skills/:

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

Полное руководство по использованию, ожидаемые результаты, устранение неполадок и запрос новых функций — см. SKILLS.md.

Навыки ссылаются на инструменты MCP по их обычным именам (get_firewall_policies, …); ваш MCP-клиент добавляет к ним префикс автоматически.

Поддерживаемое оборудование

• UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)

• UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)

• UniFi Network Video Recorder (UNVR, UNVR-Pro)

• UniFi Network Application (self-hosted)

• Классический Cloud Key (Gen1, Gen2, Gen2+)

Установка

Использование uv (рекомендуется)

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

Использование pip

pip install -e .

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

Создайте файл .env в корне проекта (или задайте переменные окружения). Все параметры перечислены в .env.example.

Конфигурация нескольких устройств (рекомендуется)

Настройте несколько устройств UniFi с разными сервисами:

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

Поля конфигурации устройства:

Примечание: поля username и password требуются только для инструментов событий Protect (события движения, умные детекции). Базовые операции с камерами работают только с API-ключом.

Чтобы создать API-ключ:

1. Войдите в ваш контроллер UniFi

2. Перейдите в Настройки → Control Plane → API

3. Создайте новый API-ключ с необходимыми правами

Устаревшая конфигурация одного устройства

Для обратной совместимости по-прежнему поддерживается конфигурация одного устройства:

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

Локальная сессионная аутентификация (традиционная)

Для доступа ко всем функциям с аутентификацией по имени пользователя и паролю:

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API (api.ui.com)

Для доступа к Ubiquiti Cloud API:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

Получите API-ключ на unifi.ui.com → в разделе API.

Использование с Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/.config/claude/claude_desktop_config.json в Linux или ~/Library/Application Support/Claude/claude_desktop_config.json в macOS):

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Использование с Claude Code / opencode

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

Или в opencode.json:

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

Доступные инструменты

Управление несколькими устройствами

• list_unifi_devices - список всех настроенных устройств UniFi и их сервисов

Управление устройствами

• list_devices - список всех сетевых устройств UniFi

• get_device_details - получение подробной информации об устройстве

• restart_device - перезагрузка устройства

• locate_device - мигание светодиодом для поиска устройства

• get_device_stats - получение статистики производительности

• upgrade_device - обновление прошивки

• provision_device - принудительное повторное применение конфигурации

Управление клиентами

• list_clients - список подключённых клиентов

• list_all_clients - список всех известных клиентов (включая офлайн)

• get_client_details - получение сведений о клиенте

• block_client / unblock_client - блокировка/разблокировка клиентов

• kick_client - отключение клиента

• forget_client - удаление из известных клиентов

• get_client_traffic - получение статистики трафика

• reserve_client_ip - резервирование IP через DHCP-резервацию

Управление сайтами

• list_sites - список всех сайтов

• get_site_health - получение состояния сайта

• get_site_settings - получение настроек сайта

• get_sysinfo - получение системной информации

• get_networks - получение конфигураций сетей/VLAN

• get_wlans - получение конфигураций беспроводных сетей

• get_port_profiles - получение профилей портов коммутатора

• get_firewall_rules - получение устаревших правил брандмауэра

• get_firewall_policies - получение зональных политик брандмауэра (UniFi Network 9+)

• get_routing_table - получение таблицы маршрутизации

• get_port_forwards - получение правил проброса портов

• create_port_forward / delete_port_forward - управление пробросом портов

Управление конфигурацией (запись)

• create_wlan / update_wlan / delete_wlan - Управление беспроводными сетями

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - Управление зональными политиками межсетевого экрана

• export_camera_clip - Экспорт записи с камеры в формате MP4 (Protect)

• get_all_sites_health - Обзор состояния всех сайтов

Инструменты, которые удаляют данные или вызывают нарушения в работе, требуют подтверждения или помечаются как деструктивные через аннотации MCP.

Статистика и мониторинг

• get_network_health - Общее состояние сети

• get_recent_events - Последние события

• get_alarms - Активные тревоги

• archive_all_alarms - Архивация всех тревог

• run_speed_test - Запуск теста скорости

• get_speed_test_status - Получение результатов теста скорости

• get_dpi_stats - Статистика DPI

• get_traffic_summary - Сводка по трафику

Инструменты ИИ-аналитики

• analyze_network_issues - Комплексный анализ проблем

• get_optimization_recommendations - Рекомендации по конфигурации

• get_client_experience_report - Метрики качества обслуживания клиентов

• get_device_health_summary - Обзор состояния устройств

• get_traffic_analysis - Анализ структуры трафика

• get_all_sites_health - Обзор состояния всех сайтов

Оркестрация нескольких сайтов

• get_global_inventory - Единая инвентаризация устройств по всем контроллерам

• get_global_health - Сводный отчёт о состоянии по всем контроллерам

• get_global_client_summary - Количество клиентов, самые активные по трафику, заблокированные клиенты по всем контроллерам

• troubleshoot_client - Углублённая диагностика клиента

UniFi Protect

• list_cameras - Список всех камер со статусом подключения

• get_camera_details - Подробная информация о камере

• get_camera_snapshot - Живой снимок (base64 JPEG)

• get_protect_system_info - Информация о системе NVR

• get_camera_health_summary - Обзор состояния камер с проблемами

• get_liveviews - Настроенные раскладки liveview

• get_protect_accessories - Список светильников, датчиков, звонков и просмотрщиков

События UniFi Protect (требуются имя пользователя и пароль)

• get_motion_events - Последние события движения

• get_smart_detections - События умного обнаружения (человек, транспорт, животное, посылка)

• get_protect_event_summary - Сводка всех событий по типам

• get_recent_protect_activity - Быстрый обзор последней активности

Примеры диалогов

После подключения MCP-сервера вы можете спросить Claude:

Управление сетью

• «Перечисли все мои устройства UniFi»

• «Каково текущее состояние сети?»

• «Проанализируй мою сеть на наличие проблем»

• «Какие рекомендации по оптимизации у тебя есть?»

• «Покажи метрики качества обслуживания клиентов»

• «Проведи диагностику клиента с MAC-адресом aa:bb:cc:dd:ee:ff»

• «Какие клиенты используют больше всего пропускной способности?»

• «Есть ли устройства, которым нужны обновления прошивки?»

• «Покажи последние события сети»

• «Запусти тест скорости»

UniFi Protect

• «Перечисли все мои камеры»

• «Покажи сводку о состоянии камер»

• «Получи снимок с камеры Front Door»

• «Каков статус моего NVR?»

• «Есть ли отключённые камеры?»

• «Покажи аксессуары Protect»

События Protect (требуются учётные данные)

• «Покажи последние события движения»

• «Какие умные обнаружения произошли за последние 24 часа?»

• «Были ли сегодня обнаружения людей?»

• «Дай сводку событий за прошедшую неделю»

• «Покажи последнюю активность камеры Front Door»

Несколько устройств

• «Перечисли мои настроенные устройства UniFi»

• «Покажи камеры на моём NVR»

• «Получи состояние сети от основного шлюза»

Разработка

Запуск тестов

uv run pytest

Форматирование кода

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

Запрос нового функционала

• Новые навыки: Откройте issue с префиксом [Skill] — опишите проблему, рабочий процесс и ожидаемый результат

• Изменение навыков: Откройте issue с префиксом [Skill: skill-name] — чего не хватает или что не работает

• Новые инструменты: Откройте issue с префиксом [Tool] — укажите конечную точку API UniFi и ожидаемый формат

Подробные рекомендации по участию в разработке см. в SKILLS.md.

Историю релизов см. в CHANGELOG.md, а информацию о том, как внести вклад, — в CONTRIBUTING.md.

Примечания по безопасности

• Учётные данные передаются через переменные окружения — никогда не коммитьте .env

• Проверка SSL отключена по умолчанию для самоподписанных сертификатов

• Сервер предоставляет только операции чтения и безопасные команды управления

• Деструктивные операции (удаление сайта, сброс к заводским настройкам) недоступны

• API-ключи следует хранить в безопасности и периодически ротировать

Лицензия

MIT License

Участие в разработке

Вклад приветствуется! Пожалуйста, откройте issue или отправьте pull request.