NinjaOne MCP Server

Сервер Model Context Protocol (MCP) для взаимодействия с NinjaOne, использующий архитектуру дерева решений для эффективной загрузки инструментов.

Развертывание в один клик

[!IMPORTANT] Перед нажатием: этот сервер зависит от @wyre-technology/node-ninjaone, который размещается в npm-реестре GitHub Packages. У GitHub Packages нет анонимного доступа — даже если пакет публичный, каждый npm install требует токен. Облачный сборщик выполняет npm install за вас, поэтому вы должны предоставить его, иначе сборка завершится с ошибкой npm error 401 Unauthorized ... npm.pkg.github.com.

1. Создайте Personal Access Token GitHub с областью read:packages (классический токен). Подойдет любой аккаунт GitHub — вам не нужно быть участником организации wyre-technology, чтобы читать её публичные пакеты.

2. Добавьте его как переменную сборки, когда развертывание запросит:

   • Cloudflare Workers → установите переменную сборки с именем NODE_AUTH_TOKEN равной вашему PAT (Workers → Settings → Build → Variables and Secrets).

   • DigitalOcean App Platform → установите зашифрованную переменную окружения с именем GITHUB_TOKEN с областью Build Time равной вашему PAT (в .do/app.yaml она уже объявлена).

[!NOTE] Обе цели запускают полный MCP-сервер. DigitalOcean собирает Docker-образ и обслуживает его по HTTP; Cloudflare Workers обслуживает тот же сервер через Web Standard Streamable HTTP транспорт SDK (src/worker.ts). После развертывания задайте свои учетные данные NinjaOne как секреты — NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET и, при необходимости, NINJAONE_REGION — или установите AUTH_MODE=gateway, чтобы принимать учетные данные в каждом запросе из заголовков X-Ninja-*. Конечная точка MCP — /mcp; /health — это неаутентифицированный зонд готовности.

Архитектура

Этот MCP-сервер использует иерархический подход к загрузке инструментов вместо того, чтобы показывать все инструменты сразу:

1. Фаза навигации: изначально доступен только навигационный инструмент (ninjaone_navigate)

2. Выбор домена: пользователь выбирает домен (устройства, организации, оповещения, тикеты)

3. Инструменты домена: сервер предоставляет инструменты, специфичные для домена, после выбора

4. Ленивая загрузка: обработчики доменов и клиент NinjaOne загружаются по требованию

Эта архитектура обеспечивает:

• Снижение когнитивной нагрузки (меньше инструментов на выбор)

• Более быструю начальную загрузку

• Лучшую организацию связанных операций

• Четкое состояние навигации

Установка

Этот пакет публикуется в npm-реестр GitHub Packages, который требует токен даже для публичных пакетов. Аутентифицируйтесь один раз, затем установите:

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-technology/ninjaone-mcp

.npmrc в репозитории уже указывает область @wyre-technology на GitHub Packages и читает токен из NODE_AUTH_TOKEN, поэтому дополнительная настройка не требуется. То же самое относится и к npx @wyre-technology/ninjaone-mcp ниже. Предпочитаете вариант без настройки? Используйте предварительно собранный контейнерный образ (ghcr.io/wyre-technology/ninjaone-mcp) или пакет .mcpb, прикрепленный к каждому релизу.

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

Задайте следующие переменные окружения:

Регионы API NinjaOne

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

Запуск в автономном режиме

# Set credentials
export NINJAONE_CLIENT_ID="your-client-id"
export NINJAONE_CLIENT_SECRET="your-client-secret"
export NINJAONE_REGION="us"

# Run the server
npx @wyre-technology/ninjaone-mcp

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

Добавьте в ваш claude_desktop_config.json для Claude Desktop:

{
  "mcpServers": {
    "ninjaone": {
      "command": "npx",
      "args": ["@wyre-technology/ninjaone-mcp"],
      "env": {
        "NINJAONE_CLIENT_ID": "your-client-id",
        "NINJAONE_CLIENT_SECRET": "your-client-secret",
        "NINJAONE_REGION": "us"
      }
    }
  }
}

Docker

docker build -t ninjaone-mcp .
docker run -e NINJAONE_CLIENT_ID=xxx -e NINJAONE_CLIENT_SECRET=xxx -e NINJAONE_REGION=us ninjaone-mcp

Доступные домены

Устройства

Управление конечными точками, перезагрузка устройств, просмотр служб и оповещений.

Инструменты:

• ninjaone_devices_list — список устройств с фильтрацией по организации, классу устройства и статусу онлайн. Пагинация: полная страница возвращает hasMore: true и cursor для передачи на следующую страницу.

• ninjaone_devices_get — получить сведения об устройстве

• ninjaone_devices_reboot — запланировать перезагрузку устройства

• ninjaone_devices_services — список служб Windows на устройстве

• ninjaone_devices_alerts — получить оповещения, специфичные для устройства

• ninjaone_devices_activities — просмотр журнала активности устройства

Организации

Управление организациями клиентов и их ресурсами.

Инструменты:

• ninjaone_organizations_list — список организаций

• ninjaone_organizations_get — получить сведения об организации

• ninjaone_organizations_create — создать новую организацию

• ninjaone_organizations_locations — список местоположений организации

• ninjaone_organizations_devices — список устройств для организации

Оповещения

Просмотр и управление оповещениями на всех устройствах.

Инструменты:

• ninjaone_alerts_list — список оповещений с фильтрами

• ninjaone_alerts_get — получить одно оповещение по UID (отображается как интерактивная карточка в хостах MCP Apps)

• ninjaone_alerts_reset — сбросить/отклонить одно оповещение

• ninjaone_alerts_reset_all — сбросить все оповещения для устройства или организации

• ninjaone_alerts_summary — получить сводку по количеству оповещений

Возможности:

• Интерактивная карточка оповещения (MCP Apps, SEP-1865): ninjaone_alerts_get отображается как интерактивная карточка в хостах MCP Apps (Claude Desktop/web) с циклом «Сбросить оповещение» внутри карточки через ninjaone_alerts_reset; нейтральная по умолчанию, настраиваемая через инъекцию window.__BRAND__ или переменные окружения MCP_BRAND_*; поведение с обычным JSON не изменяется в других хостах

Тикеты

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

Инструменты:

• ninjaone_tickets_list — список тикетов с доски (требуется board_id; фильтры status/organization_id/device_id применяются на стороне клиента, см. примечания ниже)

• ninjaone_tickets_get — получить сведения о тикете

• ninjaone_tickets_create — создать новый тикет

• ninjaone_tickets_update — обновить существующий тикет

• ninjaone_tickets_add_comment — добавить комментарий к тикету

• ninjaone_tickets_comments — получить комментарии к тикету

• ninjaone_tickets_boards_list — список досок тикетов (для обнаружения значений board_id)

Примечание: NinjaOne запрашивает тикеты по доскам, и идентификаторы досок различаются в зависимости от тенанта — доска 1 не всегда является доской «Все тикеты», поэтому ninjaone_tickets_list требует явный board_id, а не молча угадывает его. Узнайте идентификаторы с помощью ninjaone_tickets_boards_list; в тенантах, где эта конечная точка возвращает 404, прочитайте числовой идентификатор из URL ссылки на доску в веб-интерфейсе NinjaOne (например, ссылка «Все тикеты» на боковой панели).

Примечание: API досок NinjaOne не может фильтровать тикеты по статусу, организации или устройству на стороне сервера (попытка вызывает общую ошибку Bad request). Поэтому ninjaone_tickets_list применяет эти фильтры на стороне клиента в пределах одной страницы доски. Ответ разделяет count (совпадения на этой странице) и scanned (просмотренные тикеты) и включает hasMore/cursor — листайте страницы, пока hasMore не станет false, чтобы получить все совпадения, и никогда не считайте count одной страницы общим количеством по доске. Статус сопоставляется с отображаемым именем статуса каждого тикета, поэтому пользовательские статусы досок могут не соответствовать значениям OPEN/IN_PROGRESS/WAITING/CLOSED.

Аналогично, ninjaone_devices_list фильтрует по organization_id через специальную конечную точку NinjaOne для каждой организации (общий фильтр устройств df=org ненадежен и может молча возвращать весь парк устройств).

Навигационные инструменты

Всегда доступны:

• ninjaone_navigate — выбрать домен для работы

• ninjaone_status — показать текущее состояние и статус учетных данных

• ninjaone_back — вернуться в главное меню (когда находитесь в домене)

Пример рабочего процесса

User: Check my devices
Claude: [calls ninjaone_navigate with domain="devices"]
       -> Navigated to devices domain. Available tools: ...

User: List all Windows servers
Claude: [calls ninjaone_devices_list with device_class="WINDOWS_SERVER"]
       -> [device list results]

User: Now show me alerts
Claude: [calls ninjaone_back]
       -> Navigated back to main menu.
       [calls ninjaone_navigate with domain="alerts"]
       -> Navigated to alerts domain.

Аутентификация

NinjaOne использует OAuth 2.0 для аутентификации. Вам необходимо:

1. Войти в панель управления NinjaOne

2. Перейти в Administration > Apps > API

3. Создать новое API-приложение (платформа приложения: API Services, тип предоставления Client Credentials)

4. Предоставить ему необходимые области — см. ниже

5. Записать Client ID и Client Secret

6. Настроить переменные окружения

Клиентская библиотека автоматически обрабатывает обновление токена.

Области OAuth

По умолчанию сервер запрашивает monitoring management. Какие области вам фактически нужны, зависит от того, что вы используете:

Если вашему API-приложению предоставлено меньше областей, чем по умолчанию, установите NINJAONE_SCOPES в соответствии с ними. NinjaOne отклоняет запрос токена, который запрашивает область, не предоставленную приложению — он возвращает 400 invalid_scope вместо сужения предоставления — поэтому сбой происходит при обмене токена, и каждый вызов инструмента завершается ошибкой, включая чтение. Для приложения только с мониторингом:

export NINJAONE_SCOPES="monitoring"

Значения могут быть разделены запятыми или пробелами и нечувствительны к регистру. В шлюзовых развертываниях то же значение можно передавать в каждом запросе через заголовок X-Ninja-Scopes.

Лицензия

Apache-2.0