NinjaOne MCP Server

Ein Model Context Protocol (MCP)-Server für die Interaktion mit NinjaOne, der eine Entscheidungsbaum-Architektur für effizientes Laden von Tools bietet.

Ein-Klick-Bereitstellung

[!IMPORTANT] Bevor Sie klicken: Dieser Server hängt von @wyre-technology/node-ninjaone ab, das im GitHub Packages-npm-Registry gehostet wird. GitHub Packages hat keinen anonymen Zugriff – obwohl das Paket öffentlich ist, benötigt jede npm install ein Token. Der Cloud-Builder führt npm install für Sie aus, daher müssen Sie ihm eines geben, sonst schlägt der Build mit npm error 401 Unauthorized ... npm.pkg.github.com fehl.

1. Erstellen Sie ein GitHub Personal Access Token mit dem Bereich read:packages (klassisches Token). Jedes GitHub-Konto funktioniert – Sie müssen nicht Mitglied der wyre-technology-Organisation sein, um deren öffentliche Pakete zu lesen.

2. Fügen Sie es als Build-Variable hinzu, wenn Sie vom Bereitstellungsablauf dazu aufgefordert werden:

   • Cloudflare Workers → setzen Sie eine Build-Variable namens NODE_AUTH_TOKEN auf Ihr PAT (Workers → Settings → Build → Variables and Secrets).

   • DigitalOcean App Platform → setzen Sie eine verschlüsselte Umgebungsvariable namens GITHUB_TOKEN mit dem Bereich Build Time auf Ihr PAT (die .do/app.yaml deklariert sie bereits).

[!NOTE] Beide Ziele führen den vollständigen MCP-Server aus. DigitalOcean baut das Docker-Image und stellt es über HTTP bereit; Cloudflare Workers bedient denselben Server über den Web-Standard- Streamable-HTTP-Transport des SDKs (src/worker.ts). Nach der Bereitstellung setzen Sie Ihre NinjaOne-Anmeldedaten als Geheimnisse – NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, und optional NINJAONE_REGION – oder setzen Sie AUTH_MODE=gateway, um Anmeldedaten pro Anfrage aus X-Ninja-*-Headern zu übernehmen. Der MCP-Endpunkt ist /mcp; /health ist ein nicht authentifizierter Liveness-Healthcheck.

Architektur

Dieser MCP-Server verwendet einen hierarchischen Tool-Ladeansatz, anstatt alle Tools im Voraus bereitzustellen:

1. Navigationsphase: Stellt zunächst nur ein Navigationstool (ninjaone_navigate) bereit

2. Domänenauswahl: Der Benutzer wählt eine Domäne (Geräte, Organisationen, Warnungen, Tickets)

3. Domänen-Tools: Der Server stellt nach der Auswahl domänenspezifische Tools bereit

4. Lazy Loading: Domänen-Handler und der NinjaOne-Client werden bei Bedarf geladen

Diese Architektur bietet:

• Reduzierte kognitive Belastung (weniger Tools zur Auswahl)

• Schnellere anfängliche Ladezeiten

• Bessere Organisation verwandter Operationen

• Klaren Navigationszustand

Installation

Dieses Paket wird im GitHub Packages-npm-Registry veröffentlicht, das auch für öffentliche Pakete ein Token erfordert. Authentifizieren Sie sich einmal, dann installieren Sie:

# 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

Die .npmrc des Repos verweist den @wyre-technology-Bereich bereits auf GitHub Packages und liest das Token aus NODE_AUTH_TOKEN, sodass keine weitere Konfiguration erforderlich ist. Das Gleiche gilt für npx @wyre-technology/ninjaone-mcp unten. Bevorzugen Sie eine Option ohne Einrichtung? Verwenden Sie das vorgefertigte Container-Image (ghcr.io/wyre-technology/ninjaone-mcp) oder das .mcpb-Bundle, das jedem Release beiliegt.

Konfiguration

Setzen Sie die folgenden Umgebungsvariablen:

NinjaOne-API-Regionen

Verwendung

Eigenständig ausführen

# 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-Konfiguration

Fügen Sie zu Ihrer Claude-Desktop-claude_desktop_config.json hinzu:

{
  "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

Verfügbare Domänen

Geräte

Endpunkte verwalten, Geräte neu starten, Dienste und Warnungen anzeigen.

Tools:

• ninjaone_devices_list - Geräte auflisten, filterbar nach Organisation, Geräteklasse und Online-Status. Paginiert: Eine volle Seite gibt hasMore: true und einen cursor zurück, den Sie für die nächste Seite übergeben.

• ninjaone_devices_get - Gerätedetails abrufen

• ninjaone_devices_reboot - Einen Geräteneustart planen

• ninjaone_devices_services - Windows-Dienste auf einem Gerät auflisten

• ninjaone_devices_alerts - Gerätespezifische Warnungen abrufen

• ninjaone_devices_activities - Geräteaktivitätsprotokoll anzeigen

Organisationen

Kundenorganisationen und deren Ressourcen verwalten.

Tools:

• ninjaone_organizations_list - Organisationen auflisten

• ninjaone_organizations_get - Organisationsdetails abrufen

• ninjaone_organizations_create - Eine neue Organisation erstellen

• ninjaone_organizations_locations - Organisationsstandorte auflisten

• ninjaone_organizations_devices - Geräte für eine Organisation auflisten

Warnungen

Warnungen auf allen Geräten anzeigen und verwalten.

Tools:

• ninjaone_alerts_list - Warnungen mit Filtern auflisten

• ninjaone_alerts_get - Eine einzelne Warnung per UID abrufen (wird in MCP-Apps-Hosts als interaktive Karte gerendert)

• ninjaone_alerts_reset - Eine einzelne Warnung zurücksetzen/verwerfen

• ninjaone_alerts_reset_all - Alle Warnungen für ein Gerät oder eine Organisation zurücksetzen

• ninjaone_alerts_summary - Zusammenfassung der Warnungsanzahl abrufen

Funktionen:

• Interaktive Warnungskarte (MCP-Apps, SEP-1865): ninjaone_alerts_get wird in MCP-Apps-Hosts (Claude Desktop/Web) als interaktive Karte gerendert, mit einem In-Karten-Roundtrip „Warnung zurücksetzen“ über ninjaone_alerts_reset; standardmäßig neutral, markenbar über window.__BRAND__-Injektion oder MCP_BRAND_*-Umgebungsvariablen; reines JSON-Verhalten bleibt in anderen Hosts unverändert

Tickets

Service-Tickets verwalten.

Tools:

• ninjaone_tickets_list - Tickets aus einem Board auflisten (erfordert board_id; status/organization_id/device_id-Filter werden clientseitig angewendet, siehe Hinweise unten)

• ninjaone_tickets_get - Ticketdetails abrufen

• ninjaone_tickets_create - Ein neues Ticket erstellen

• ninjaone_tickets_update - Ein vorhandenes Ticket aktualisieren

• ninjaone_tickets_add_comment - Einen Kommentar zu einem Ticket hinzufügen

• ninjaone_tickets_comments - Ticketkommentare abrufen

• ninjaone_tickets_boards_list - Ticket-Boards auflisten (um board_id-Werte zu entdecken)

Hinweis: NinjaOne fragt Tickets pro Board ab, und Board-IDs variieren je nach Mandant – Board 1 ist nicht immer das „Alle Tickets“-Board, daher erfordert ninjaone_tickets_list eine explizite board_id, anstatt stillschweigend eine zu erraten. Entdecken Sie IDs mit ninjaone_tickets_boards_list; auf Mandanten, bei denen dieser Endpunkt 404 zurückgibt, lesen Sie die numerische ID aus der URL des Board-Links in der NinjaOne- Weboberfläche (z. B. den „Alle Tickets“-Seitenleistenlink).

Hinweis: Die Board-Run-API von NinjaOne kann Tickets nicht serverseitig nach Status, Organisation oder Gerät filtern (ein Versuch wirft ein generisches Bad request). ninjaone_tickets_list wendet diese Filter daher clientseitig innerhalb einer Board-Seite an. Die Antwort trennt count (Treffer auf dieser Seite) von scanned (untersuchte Tickets) und enthält hasMore/cursor – blättern Sie, bis hasMore false ist, um jeden Treffer zu erhalten, und behandeln Sie den count einer einzelnen Seite niemals als boardweite Gesamtzahl. Der Status wird mit dem Anzeigenamen des Status jedes Tickets abgeglichen, daher passen benutzerdefinierte Board-Status möglicherweise nicht auf die Werte OPEN/IN_PROGRESS/WAITING/CLOSED.

Ebenso filtert ninjaone_devices_list nach organization_id über NinjaOnes dedizierten Pro-Organisations-Endpunkt (der allgemeine df=org-Gerätefilter ist unzuverlässig und kann stillschweigend die gesamte Flotte zurückgeben).

Navigationstools

Immer verfügbar:

• ninjaone_navigate - Eine Domäne zur Bearbeitung auswählen

• ninjaone_status - Aktuellen Zustand und Anmeldedatenstatus anzeigen

• ninjaone_back - Zum Hauptmenü zurückkehren (wenn in einer Domäne)

Beispiel-Workflow

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.

Authentifizierung

NinjaOne verwendet OAuth 2.0 für die Authentifizierung. Sie müssen:

1. Sich in Ihr NinjaOne-Dashboard einloggen

2. Zu Administration > Apps > API gehen

3. Eine neue API-Anwendung erstellen (Anwendungsplattform: API Services, Gewährungstyp Client Credentials)

4. Ihr die benötigten Bereiche gewähren – siehe unten

5. Client-ID und Client-Geheimnis notieren

6. Die Umgebungsvariablen konfigurieren

Die Client-Bibliothek übernimmt die Token-Aktualisierung automatisch.

OAuth-Bereiche

Standardmäßig fordert der Server monitoring management an. Welche Bereiche Sie tatsächlich benötigen, hängt davon ab, was Sie verwenden:

Wenn Ihrer API-App weniger Bereiche gewährt wurden als standardmäßig, setzen Sie NINJAONE_SCOPES entsprechend. NinjaOne lehnt eine Token-Anfrage ab, die einen Bereich anfordert, der der App nie gewährt wurde – es gibt 400 invalid_scope zurück, anstatt die Gewährung einzuschränken – daher tritt der Fehler beim Token-Austausch auf und jeder Tool-Aufruf schlägt fehl, einschließlich Lesevorgängen. Für eine reine Überwachungs-App:

export NINJAONE_SCOPES="monitoring"

Werte können durch Kommas oder Leerzeichen getrennt sein und sind case-insensitiv. In Gateway- Bereitstellungen kann derselbe Wert pro Anfrage über den X-Ninja-Scopes-Header geliefert werden.

Lizenz

Apache-2.0