ninjaone-mcp

NinjaOne RMM MCP-сервер — предоставляет Public API v2 NinjaOne (Organizations, Devices, Alerts, Ticketing, Automation/Scripting, Jobs) в виде MCP-инструментов.

Что такое NinjaOne / когда агенту это использовать

NinjaOne — это RMM-платформа (удаленный мониторинг и управление), которую MSP используют для управления ИТ-инфраструктурой клиентов. Агенту следует обращаться к этому MCP для запросов, например:

• «Сколько устройств у этого клиента и какие из них офлайн?» → ninjaone_get_organization_devices / ninjaone_get_devices

• «Есть ли активные оповещения для этого устройства/организации?» → ninjaone_get_device_alerts / ninjaone_get_alerts

• «Какие тикеты открыты на доске поддержки?» → ninjaone_get_ticket_boards, затем ninjaone_get_tickets

• «Запустить очистку диска на этом устройстве и сообщить, когда она завершится» → ninjaone_get_device_scripting_options для проверки доступных действий, ninjaone_run_script_on_device, затем ninjaone_get_device_active_jobs для отслеживания завершения

• «Какие сценарии автоматизации у нас доступны?» → ninjaone_get_automation_scripts

Обзор

Этот сервер реализует Model Context Protocol (транспорт Streamable HTTP) с 23 инструментами в 5 группах, следуя Vendor MCP Service SOP от MSPbots: без сохранения состояния, без хранения учетных данных, аутентификация по заголовкам в каждом запросе.

Этот проект был создан на основе инструментов сообщества wyre-technology/ninjaone-mcp (organizations/devices/alerts/tickets, переработанных здесь напрямую через REST API NinjaOne, а не через его Node SDK) и расширен 5 инструментами автоматизации/скриптов/задач, взятыми из собственной спецификации OpenAPI 3.0.1 NinjaOne — каждая конечная точка ниже была проверена по реальной спецификации API NinjaOne, а не угадана или скопирована из вторичного источника.

NinjaOne аутентифицируется через OAuth2 client_credentials: client ID + secret OAuth2-приложения NinjaOne типа «API Services» обмениваются на кратковременный bearer-токен по адресу POST {base_url}/oauth/token. Этот сервер выполняет обмен самостоятельно, заново при каждом вызове инструмента — он никогда не хранит и не кэширует токен (или client_id/secret) между вызовами.

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

Docker (рекомендуется)

docker compose up --build

Локально (uv)

uv sync
python -m ninjaone_mcp

Проверка здоровья

curl http://localhost:8080/health
# {"status": "ok"}

Для конечной точки проверки здоровья учетные данные не требуются.

Описание параметров аутентификации (Аутентификация)

Каждый запрос к /mcp должен содержать следующие HTTP-заголовки:

Отсутствие любого из обязательных заголовков возвращает 401 Unauthorized.

Переменные окружения

Переменной окружения для base URL нет — base URL определяется для каждого запроса из заголовка X-Ninja-Region (см. таблицу регионов в config.py).

Конечная точка MCP

POST http://localhost:8080/mcp

Подключите ваш MCP-клиент с помощью:

• Транспорт: http (Streamable HTTP)

• Заголовки: X-Ninja-Client-Id, X-Ninja-Client-Secret (оба обязательны), X-Ninja-Region (необязательный)

Список инструментов

Пример тестирования (Пример теста)

Список досок тикетов:

{
  "method": "tools/call",
  "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
}

Эквивалентная команда curl для запущенного сервера (конечная точка MCP со streamable HTTP):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Ninja-Client-Id: <client_id>" \
  -H "X-Ninja-Client-Secret: <client_secret>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
  }'

Запуск сценария на устройстве:

{
  "method": "tools/call",
  "params": {
    "name": "ninjaone_run_script_on_device",
    "arguments": { "device_id": 123, "type": "SCRIPT", "script_id": 456 }
  }
}

Справочник по API

• Документация: https://app.ninjarmm.com/apidocs-beta/core-resources (аналоги для регионов eu/oc/ca/us2/fed)

• Аутентификация: OAuth2 client_credentials на POST /oauth/token (grant_type, client_id, client_secret, scope), области: monitoring, management, control

Известные ограничения / Примечания по реализации

• Происхождение конечных точек: 4 из 5 конечных точек автоматизации/скриптов/заданий (requestScriptingOptions, runScriptOnDevice, getActiveJobs, getDeviceActiveJobs) были перепроверены по независимо полученной копии OpenAPI-спецификации NinjaOne. getAutomationScripts отсутствовал в этой копии (он новее той редакции спецификации) — его точное расположение в пути /api выведено по подтверждённому шаблону остальных 4, а не проверено независимо. См. комментарий в начале tools/automation.py.

• ninjaone_get_tickets фильтрует на стороне клиента: схема запроса конечной точки досок NinjaOne определяет параметры filters/searchCriteria, но, по сообщениям проекта сообщества wyre-technology, на практике они возвращают 400 — этот инструмент всегда запрашивает нефильтрованную страницу и фильтрует status/organization_id/device_id на стороне клиента.

• Нет отдельной конечной точки получения одного тикета или добавления комментария: API тикетов NinjaOne не предоставляет GET /ticketing/ticket/{id} — чтобы найти один тикет, нужно пролистывать ninjaone_get_tickets по его доске. Добавление комментария также не является отдельной конечной точкой — оно включено в параметры comment/comment_public инструмента ninjaone_update_ticket, наряду с PUT по самому тикету.

• Фильтр df в ninjaone_get_devices может быть молча отброшен NinjaOne при ограничении по организации (известная проблема в проекте сообщества) — для списка устройств в рамках организации предпочтительнее использовать ninjaone_get_organization_devices.

• Пока не протестировано на живом аккаунте NinjaOne с реальными учётными данными — на данный момент проверено: tools/list возвращает все 23 инструмента с чистыми схемами, pytest (15 тестов) проходит, а живой вызов с фиктивными client_id/secret достиг реальной производственной конечной точки /oauth/token NinjaOne и получил настоящий, корректно сформированный отказ (Client app not exist), а не ошибку о некорректном запросе — что подтверждает правильность базового URL, конечной точки токена и формата запроса.