NinjaOne MCP Server

Un servidor de Model Context Protocol (MCP) para interactuar con NinjaOne, con una arquitectura de árbol de decisión para una carga eficiente de herramientas.

Despliegue con un clic

[!IMPORTANT] Antes de hacer clic: este servidor depende de @wyre-technology/node-ninjaone, que está alojado en el registro npm de GitHub Packages. GitHub Packages no tiene acceso anónimo: aunque el paquete sea público, cada npm install necesita un token. El constructor en la nube ejecuta npm install por ti, así que debes proporcionarle uno, o la compilación fallará con npm error 401 Unauthorized ... npm.pkg.github.com.

1. Crea un Personal Access Token de GitHub con el ámbito read:packages (token clásico). Cualquier cuenta de GitHub sirve: no necesitas ser miembro de la organización wyre-technology para leer sus paquetes públicos.

2. Añádelo como variable de compilación cuando el flujo de despliegue lo solicite:

   • Cloudflare Workers → establece una variable de compilación llamada NODE_AUTH_TOKEN con tu PAT (Workers → Settings → Build → Variables and Secrets).

   • DigitalOcean App Platform → establece una variable de entorno cifrada llamada GITHUB_TOKEN con ámbito Build Time con tu PAT (el .do/app.yaml ya lo declara).

[!NOTE] Ambos destinos ejecutan el servidor MCP completo. DigitalOcean construye la imagen Docker y la sirve por HTTP; Cloudflare Workers sirve el mismo servidor mediante el transporte HTTP Streamable Web Standard del SDK (src/worker.ts). Después de desplegar, establece tus credenciales de NinjaOne como secretos — NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, y opcionalmente NINJAONE_REGION — o establece AUTH_MODE=gateway para tomar credenciales por solicitud de los encabezados X-Ninja-*. El endpoint MCP es /mcp; /health es una sonda de actividad sin autenticación.

Arquitectura

Este servidor MCP utiliza un enfoque de carga jerárquica de herramientas en lugar de exponer todas las herramientas de antemano:

1. Fase de navegación: Inicialmente expone solo una herramienta de navegación (ninjaone_navigate)

2. Selección de dominio: El usuario selecciona un dominio (dispositivos, organizaciones, alertas, tickets)

3. Herramientas de dominio: El servidor expone herramientas específicas del dominio después de la selección

4. Carga diferida: Los manejadores de dominio y el cliente de NinjaOne se cargan bajo demanda

Esta arquitectura proporciona:

• Carga cognitiva reducida (menos herramientas entre las que elegir)

• Tiempos de carga inicial más rápidos

• Mejor organización de operaciones relacionadas

• Estado de navegación claro

Instalación

Este paquete se publica en el registro npm de GitHub Packages, que requiere un token incluso para paquetes públicos. Autentícate una vez y luego instala:

# 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

El .npmrc del repositorio ya apunta el ámbito @wyre-technology a GitHub Packages y lee el token de NODE_AUTH_TOKEN, por lo que no se necesita configuración adicional. Lo mismo se aplica a npx @wyre-technology/ninjaone-mcp a continuación. ¿Prefieres una opción sin configuración? Usa la imagen de contenedor precompilada (ghcr.io/wyre-technology/ninjaone-mcp) o el paquete .mcpb adjunto a cada release.

Configuración

Establece las siguientes variables de entorno:

Regiones de la API de NinjaOne

Uso

Ejecución independiente

# 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

Configuración de Claude Desktop

Añade a tu claude_desktop_config.json de 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

Dominios disponibles

Dispositivos

Gestiona endpoints, reinicia dispositivos, ve servicios y alertas.

Herramientas:

• ninjaone_devices_list - Lista dispositivos, filtrables por organización, clase de dispositivo y estado en línea. Paginado: una página completa devuelve hasMore: true y un cursor para pasarlo de vuelta en la siguiente página.

• ninjaone_devices_get - Obtiene detalles del dispositivo

• ninjaone_devices_reboot - Programa un reinicio del dispositivo

• ninjaone_devices_services - Lista los servicios de Windows en un dispositivo

• ninjaone_devices_alerts - Obtiene alertas específicas del dispositivo

• ninjaone_devices_activities - Ve el registro de actividad del dispositivo

Organizaciones

Gestiona organizaciones de clientes y sus recursos.

Herramientas:

• ninjaone_organizations_list - Lista organizaciones

• ninjaone_organizations_get - Obtiene detalles de la organización

• ninjaone_organizations_create - Crea una nueva organización

• ninjaone_organizations_locations - Lista ubicaciones de la organización

• ninjaone_organizations_devices - Lista dispositivos de una organización

Alertas

Ve y gestiona alertas en todos los dispositivos.

Herramientas:

• ninjaone_alerts_list - Lista alertas con filtros

• ninjaone_alerts_get - Obtiene una sola alerta por UID (se muestra como una tarjeta interactiva en los hosts de MCP Apps)

• ninjaone_alerts_reset - Restablece/descarta una sola alerta

• ninjaone_alerts_reset_all - Restablece todas las alertas de un dispositivo u organización

• ninjaone_alerts_summary - Obtiene un resumen del recuento de alertas

Características:

• Tarjeta de alerta interactiva (MCP Apps, SEP-1865): ninjaone_alerts_get se muestra como una tarjeta interactiva en los hosts de MCP Apps (Claude Desktop/web) con un viaje de ida y vuelta "Restablecer alerta" dentro de la tarjeta mediante ninjaone_alerts_reset; neutral por defecto, personalizable mediante la inyección de window.__BRAND__ o las variables de entorno MCP_BRAND_*; el comportamiento JSON plano no cambia en otros hosts

Tickets

Gestiona tickets de servicio.

Herramientas:

• ninjaone_tickets_list - Lista tickets de un tablero (requiere board_id; los filtros status/organization_id/device_id se aplican en el cliente, ver notas a continuación)

• ninjaone_tickets_get - Obtiene detalles del ticket

• ninjaone_tickets_create - Crea un nuevo ticket

• ninjaone_tickets_update - Actualiza un ticket existente

• ninjaone_tickets_add_comment - Añade un comentario a un ticket

• ninjaone_tickets_comments - Obtiene comentarios del ticket

• ninjaone_tickets_boards_list - Lista tableros de tickets (para descubrir valores de board_id)

Nota: NinjaOne consulta tickets por tablero, y los IDs de tablero varían según el tenant — el tablero 1 no es siempre el tablero "Todos los tickets", por lo que ninjaone_tickets_list requiere un board_id explícito en lugar de adivinar uno silenciosamente. Descubre los IDs con ninjaone_tickets_boards_list; en tenants donde ese endpoint devuelve 404, lee el ID numérico de la URL del enlace del tablero en la interfaz web de NinjaOne (por ejemplo, el enlace "Todos los tickets" en la barra lateral).

Nota: La API de ejecución de tableros de NinjaOne no puede filtrar tickets por estado, organización o dispositivo en el servidor (intentarlo lanza un error genérico Bad request). Por lo tanto, ninjaone_tickets_list aplica esos filtros en el cliente dentro de una página de tablero. La respuesta separa count (coincidencias en esta página) de scanned (tickets examinados) e incluye hasMore/cursor — pagina hasta que hasMore sea false para obtener todas las coincidencias, y nunca trates el count de una sola página como un total del tablero. El estado se compara con el nombre de visualización del estado de cada ticket, por lo que los estados personalizados del tablero pueden no corresponder a los valores OPEN/IN_PROGRESS/WAITING/CLOSED.

De manera similar, ninjaone_devices_list filtra por organization_id mediante el endpoint dedicado por organización de NinjaOne (el filtro general de dispositivos df=org no es fiable y puede devolver silenciosamente toda la flota).

Herramientas de navegación

Siempre disponibles:

• ninjaone_navigate - Selecciona un dominio con el que trabajar

• ninjaone_status - Muestra el estado actual y el estado de las credenciales

• ninjaone_back - Vuelve al menú principal (cuando estás en un dominio)

Ejemplo de flujo de trabajo

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.

Autenticación

NinjaOne utiliza OAuth 2.0 para la autenticación. Necesitas:

1. Inicia sesión en tu panel de NinjaOne

2. Ve a Administración > Aplicaciones > API

3. Crea una nueva aplicación API (plataforma de aplicación: API Services, tipo de concesión Client Credentials)

4. Concédele los ámbitos que necesites — ver más abajo

5. Anota el Client ID y el Client Secret

6. Configura las variables de entorno

La biblioteca cliente maneja la renovación del token automáticamente.

Ámbitos de OAuth

Por defecto, el servidor solicita monitoring management. Los ámbitos que realmente necesitas dependen de lo que uses:

Si a tu aplicación API se le conceden menos ámbitos que los predeterminados, establece NINJAONE_SCOPES para que coincidan. NinjaOne rechaza una solicitud de token que pide un ámbito que la aplicación nunca recibió — devuelve 400 invalid_scope en lugar de reducir la concesión — por lo que el fallo ocurre en el intercambio de tokens y cada llamada a herramienta falla, incluidas las lecturas. Para una aplicación solo de monitoreo:

export NINJAONE_SCOPES="monitoring"

Los valores pueden estar separados por comas o espacios y no distinguen entre mayúsculas y minúsculas. En despliegues de gateway, el mismo valor se puede proporcionar por solicitud mediante el encabezado X-Ninja-Scopes.

Licencia

Apache-2.0