ninjaone-mcp

NinjaOne RMM servidor MCP: expone la API pública v2 de NinjaOne (organizaciones, dispositivos, alertas, tickets, automatización/scripts, trabajos) como herramientas MCP.

Qué es NinjaOne / cuándo debería usarlo un agente

NinjaOne es una plataforma RMM (monitoreo y gestión remota) que los proveedores de servicios gestionados (MSP) usan para administrar las flotas de TI de sus clientes. Un agente debería recurrir a este MCP para solicitudes como:

• "¿Cuántos dispositivos tiene este cliente y cuáles están sin conexión?" → ninjaone_get_organization_devices / ninjaone_get_devices

• "¿Hay alertas activas para este dispositivo/organización?" → ninjaone_get_device_alerts / ninjaone_get_alerts

• "¿Qué tickets están abiertos en el tablero de soporte?" → ninjaone_get_ticket_boards y luego ninjaone_get_tickets

• "Ejecuta la limpieza de disco en este dispositivo y avísame cuando termine" → ninjaone_get_device_scripting_options para confirmar qué se puede ejecutar, ninjaone_run_script_on_device y luego ninjaone_get_device_active_jobs para ver cuándo termina

• "¿Qué scripts de automatización tenemos disponibles?" → ninjaone_get_automation_scripts

Descripción general

Este servidor implementa el Protocolo de contexto de modelo (transporte HTTP Streamable) con 23 herramientas en 5 grupos, siguiendo el estándar Vendor MCP Service SOP de MSPbots: sin estado, sin credenciales almacenadas y autenticación por cabecera en cada solicitud.

Se construyó a partir de la superficie de herramientas del proyecto comunitario wyre-technology/ninjaone-mcp (organizaciones/dispositivos/alertas/tickets, reimplementadas aquí directamente contra la API REST de NinjaOne en lugar de su SDK de Node) y se amplía con 5 herramientas de automatización/scripts/trabajos extraídas de la especificación OpenAPI 3.0.1 de NinjaOne; cada endpoint a continuación se verificó contra una especificación real de la API de NinjaOne, no se adivinó ni se copió de una fuente secundaria.

NinjaOne autentica mediante OAuth2 client_credentials: el ID de cliente y el secreto de una aplicación OAuth2 de "API Services" de NinjaOne se intercambian por un token de portador de corta duración en POST {base_url}/oauth/token. Este servidor realiza ese intercambio por sí mismo, de nuevo en cada llamada a la herramienta; nunca almacena ni guarda en caché un token (ni el client_id/secreto) entre llamadas.

Inicio rápido

Docker (recomendado)

docker compose up --build

El servidor se inicia en http://localhost:8080.

Local (uv)

uv sync
python -m ninjaone_mcp

Comprobación de estado

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

No se requieren credenciales para el endpoint de estado.

Parámetros de autenticación

Cada solicitud a /mcp debe incluir las siguientes cabeceras HTTP:

Si falta alguna de las cabeceras obligatorias, se devuelve 401 No autorizado.

Variables de entorno

No hay variable de entorno para la URL base: la URL base se deriva por solicitud de la cabecera X-Ninja-Region (consulta la tabla de regiones en config.py).

Endpoint MCP

POST http://localhost:8080/mcp

Conecta tu cliente MCP con:

• Transporte: http (HTTP Streamable)

• Cabeceras: X-Ninja-Client-Id, X-Ninja-Client-Secret (ambas obligatorias), X-Ninja-Region (opcional)

Lista de herramientas

Ejemplo de prueba

Listar tableros de tickets:

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

Equivalente en curl contra el servidor en ejecución (endpoint MCP HTTP Streamable):

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": {} }
  }'

Ejecutar un script en un dispositivo:

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

Referencia de la API

• Documentación: https://app.ninjarmm.com/apidocs-beta/core-resources (equivalentes por región para eu/oc/ca/us2/fed)

• Autenticación: concesión OAuth2 client_credentials en POST /oauth/token (grant_type, client_id, client_secret, scope), ámbitos: monitoring, management, control

Limitaciones conocidas / Notas de implementación

• Procedencia de los endpoints: 4 de los 5 endpoints de automatización/scripting/trabajos (requestScriptingOptions, runScriptOnDevice, getActiveJobs, getDeviceActiveJobs) se contrastaron con una copia obtenida de forma independiente de la especificación OpenAPI de NinjaOne. getAutomationScripts no estaba presente en esa copia (es más reciente que esa revisión de la especificación); su ubicación exacta en la ruta /api se infiere del patrón confirmado de los otros 4, no se verificó de forma independiente. Véase el comentario al principio de tools/automation.py.

• ninjaone_get_tickets filtra en el lado del cliente: el esquema de solicitud del endpoint de tablero de NinjaOne define los parámetros filters/searchCriteria, pero el proyecto comunitario wyre-technology informa de que estos devuelven un error 400 en la práctica; esta herramienta siempre solicita una página sin filtrar y filtra status/organization_id/device_id en el lado del cliente.

• No existe un endpoint de obtención de ticket individual ni de añadir comentario de forma independiente: la API de ticketing de NinjaOne no expone un GET /ticketing/ticket/{id}; para consultar un ticket, hay que recorrer las páginas de ninjaone_get_tickets en su tablero. Añadir un comentario tampoco es un endpoint independiente: está integrado en los parámetros comment/comment_public de ninjaone_update_ticket, junto con un PUT sobre el propio ticket.

• El filtro df de ninjaone_get_devices puede ser descartado silenciosamente por NinjaOne al acotar por organización (un problema conocido en el proyecto comunitario); se prefiere ninjaone_get_organization_devices para una lista de dispositivos acotada por organización.

• Aún no se ha probado contra una cuenta real de NinjaOne con credenciales reales; lo verificado hasta ahora: tools/list devuelve las 23 herramientas con esquemas limpios, pytest (15 pruebas) pasa, y una llamada en vivo con un client_id/secret ficticio llegó al endpoint real de producción /oauth/token de NinjaOne y obtuvo un rechazo real y bien formado (Client app not exist) en lugar de un error de solicitud mal formada, lo que confirma que la URL base, el endpoint de token y el formato de solicitud son correctos.