ninjaone-mcp

NinjaOne RMM-MCP-Server – stellt NinjaOnes Public API v2 (Organizations, Devices, Alerts, Ticketing, Automation/Scripting, Jobs) als MCP-Tools bereit.

Was ist NinjaOne / wann sollte ein Agent dies verwenden

NinjaOne ist eine RMM-Plattform (Remote Monitoring and Management), die MSPs zur Verwaltung der IT-Umgebungen ihrer Kunden einsetzen. Ein Agent sollte dieses MCP für Anfragen wie die folgenden verwenden:

• „Wie viele Geräte hat dieser Kunde und welche sind offline?" → ninjaone_get_organization_devices / ninjaone_get_devices

• „Gibt es aktive Alerts für dieses Gerät/diese Organisation?" → ninjaone_get_device_alerts / ninjaone_get_alerts

• „Welche Tickets sind im Support-Board offen?" → ninjaone_get_ticket_boards, dann ninjaone_get_tickets

• „Führe die Datenträgerbereinigung auf diesem Gerät aus und sag mir, wann sie fertig ist" → ninjaone_get_device_scripting_options, um zu bestätigen, was ausführbar ist, ninjaone_run_script_on_device, dann ninjaone_get_device_active_jobs, um den Abschluss zu beobachten

• „Welche Automatisierungsskripte haben wir verfügbar?" → ninjaone_get_automation_scripts

Überblick

Dieser Server implementiert das Model Context Protocol (Streamable-HTTP-Transport) mit 23 Tools in 5 Gruppen und folgt dabei der MSPbots Vendor MCP Service SOP: zustandslos, keine gespeicherten Anmeldedaten, Authentifizierung per Header bei jeder Anfrage.

Dieses Projekt wurde ausgehend von der Tool-Oberfläche des Community-Projekts wyre-technology/ninjaone-mcp (Organizations/Devices/Alerts/Tickets, hier direkt gegen NinjaOnes REST-API statt gegen sein Node SDK neu implementiert) erstellt und um 5 Automatisierungs-/Skript-/Job-Tools erweitert, die aus NinjaOnes eigener OpenAPI-3.0.1-Spezifikation stammen – jeder unten aufgeführte Endpunkt wurde gegen eine echte NinjaOne-API-Spezifikation geprüft, nicht geraten oder aus einer Sekundärquelle kopiert.

NinjaOne authentifiziert über OAuth2 client_credentials: Die Client-ID und das Secret einer NinjaOne-OAuth2-App vom Typ „API Services" werden unter POST {base_url}/oauth/token gegen ein kurzlebiges Bearer-Token eingetauscht. Dieser Server führt diesen Austausch selbst durch, bei jedem Tool-Aufruf neu – er speichert oder cached niemals ein Token (oder die client_id/das Secret) über Aufrufe hinweg.

Schnellstart

Docker (empfohlen)

docker compose up --build

Lokal (uv)

uv sync
python -m ninjaone_mcp

Health-Check

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

Für den Health-Check-Endpunkt sind keine Anmeldedaten erforderlich.

Authentifizierungsparameter

Jede Anfrage an /mcp muss die folgenden HTTP-Header enthalten:

Fehlt einer der beiden erforderlichen Header, wird 401 Unauthorized zurückgegeben.

Umgebungsvariablen

Es gibt keine Env-Variable für die Basis-URL – die Basis-URL wird pro Anfrage aus dem X-Ninja-Region-Header abgeleitet (siehe Regionstabelle in config.py).

MCP-Endpunkt

POST http://localhost:8080/mcp

Verbinden Sie Ihren MCP-Client mit den folgenden Einstellungen:

• Transport: http (Streamable HTTP)

• Header: X-Ninja-Client-Id, X-Ninja-Client-Secret (beide erforderlich), X-Ninja-Region (optional)

Tool-Liste

Testbeispiel

Ticket-Boards auflisten:

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

Entsprechender curl-Aufruf gegen den laufenden Server (Streamable-HTTP-MCP-Endpunkt):

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

Ein Skript auf einem Gerät ausführen:

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

API-Referenz

• Dokumentation: https://app.ninjarmm.com/apidocs-beta/core-resources (regionsspezifische Entsprechungen für eu/oc/ca/us2/fed)

• Authentifizierung: OAuth2-client_credentials-Grant unter POST /oauth/token (grant_type, client_id, client_secret, scope), Scopes: monitoring, management, control

Bekannte Lücken / Hinweise zur Implementierung

• Endpunkt-Herkunft: 4 der 5 Automatisierungs-/Skript-/Jobs-Endpunkte (requestScriptingOptions, runScriptOnDevice, getActiveJobs, getDeviceActiveJobs) wurden gegen eine unabhängig beschaffte Kopie der OpenAPI-Spezifikation von NinjaOne gegengeprüft. getAutomationScripts war in dieser Kopie nicht enthalten (es ist neuer als diese Spezifikationsrevision) — seine genaue /api-Pfadplatzierung wird aus dem bestätigten Muster der anderen 4 abgeleitet, nicht unabhängig verifiziert. Siehe den Kommentar am Anfang von tools/automation.py.

• ninjaone_get_tickets filtert clientseitig: Das Anforderungsschema des Board-Run-Endpunkts von NinjaOne definiert die Parameter filters/searchCriteria, aber das Community-Projekt wyre-technology berichtet, dass diese in der Praxis 400 zurückgeben — dieses Tool fordert immer eine ungefilterte Seite an und filtert stattdessen status/organization_id/device_id clientseitig.

• Kein Endpunkt zum Abrufen einzelner Tickets oder zum eigenständigen Hinzufügen von Kommentaren: Die Ticketing-API von NinjaOne stellt keinen GET /ticketing/ticket/{id} bereit — um ein einzelnes Ticket nachzuschlagen, blättere durch ninjaone_get_tickets auf dessen Board. Das Hinzufügen eines Kommentars ist ebenfalls kein separater Endpunkt — es ist in die Parameter comment/comment_public von ninjaone_update_ticket integriert, zusammen mit einem PUT auf das Ticket selbst.

• Der df-Filter von ninjaone_get_devices kann stillschweigend verworfen werden von NinjaOne bei der Eingrenzung nach Organisation (ein bekanntes Problem im Community-Projekt) — bevorzuge ninjaone_get_organization_devices für eine organisationsbezogene Geräteliste.

• Noch nicht gegen ein Live-NinjaOne-Konto mit echten Anmeldedaten getestet — bisher verifiziert: tools/list gibt alle 23 Tools mit sauberen Schemas zurück, pytest (15 Tests) besteht, und ein Live-Aufruf mit einer Dummy-client_id/secret erreichte den echten Produktions-/oauth/token-Endpunkt von NinjaOne und erhielt eine echte, wohlgeformte Ablehnung (Client app not exist) zurück, anstatt eines Fehlers wegen fehlerhafter Anfrage — was bestätigt, dass Basis-URL, Token-Endpunkt und Anforderungsformat korrekt sind.