ninjaone-mcp

NinjaOne RMM MCP server — exposes NinjaOne's Public API v2 (Organizations, Devices, Alerts, Ticketing, Automation/Scripting, Jobs) as MCP tools.

What is NinjaOne / when would an agent use this

NinjaOne is an RMM (remote monitoring and management) platform MSPs use to manage clients' IT fleets. An agent should reach for this MCP for requests like:

• "How many devices does this customer have, and which are offline?" → ninjaone_get_organization_devices / ninjaone_get_devices

• "Any active alerts for this device/org?" → ninjaone_get_device_alerts / ninjaone_get_alerts

• "What tickets are open on the support board?" → ninjaone_get_ticket_boards then ninjaone_get_tickets

• "Run disk cleanup on this device and tell me when it's done" → ninjaone_get_device_scripting_options to confirm what's runnable, ninjaone_run_script_on_device, then ninjaone_get_device_active_jobs to watch it finish

• "What automation scripts do we have available?" → ninjaone_get_automation_scripts

Overview

This server implements the Model Context Protocol (Streamable HTTP transport) with 23 tools across 5 groups, following the MSPbots Vendor MCP Service SOP: stateless, no stored credentials, per-request header authentication.

This was built starting from the community wyre-technology/ninjaone-mcp project's tool surface (organizations/devices/alerts/tickets, reimplemented here directly against NinjaOne's REST API rather than its Node SDK) and extends it with 5 automation/scripting/jobs tools pulled from NinjaOne's own OpenAPI 3.0.1 spec — every endpoint below was checked against a real NinjaOne API spec, not guessed or copied from a secondary source.

The gateway does the OAuth2 exchange, not this server. NinjaOne authenticates via OAuth2 (client_credentials for a machine identity, refresh_token for a user identity — see below); this server takes only the already-exchanged bearer access token via header and calls NinjaOne's REST API directly with it. It never sees a client_id/client_secret/refresh_token, never talks to /oauth/token, and never caches anything — whoever operates the gateway is responsible for minting and refreshing tokens before they expire (NinjaOne's access tokens last 1 hour).

One tool needs a second identity. ninjaone_run_script_on_device is believed to be rejected by NinjaOne when called with a machine (API Services app) token regardless of scope, because NinjaOne ties script execution to a real user for its audit trail — this is the working hypothesis behind the design below, not yet independently confirmed against a real device/script by this repo. That tool alone takes a second, optional bearer token — one the gateway exchanged via the refresh_token grant against a NinjaOne "Web Application" app (which requires a one-time human browser authorization to obtain the refresh token in the first place). The other 22 tools are unaffected either way.

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m ninjaone_mcp

Health Check

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

No credentials are required for the health endpoint.

授权参数说明 (Authentication)

Every request to /mcp must include the following HTTP headers:

Missing X-Ninja-Token returns 401 Unauthorized. Missing the optional X-Ninja-User-Token only affects ninjaone_run_script_on_device (returns a not_configured error) — every other tool works fine without it.

Environment Variables

There is no base-URL env var — the base URL is derived per-request from the X-Ninja-Region header (see config.py's region table).

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP)

• Headers: X-Ninja-Token (required, an already-exchanged bearer access token), X-Ninja-Region (optional), X-Ninja-User-Token (optional, only for ninjaone_run_script_on_device)

Tool List

测试示例 (Test Example)

List ticket boards:

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

Equivalent curl against the running server (streamable HTTP MCP endpoint):

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

Running a script on a device:

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

API Reference

• Documentation: https://app.ninjarmm.com/apidocs-beta/core-resources (per-region equivalents for eu/oc/ca/us2/fed)

• Auth: OAuth2 (the gateway's job, not this server's) — client_credentials grant for the machine identity, refresh_token grant for the user identity, both at POST /oauth/token; scopes for the machine identity: monitoring, management, control

Known Gaps / Implementation Notes

• Endpoint provenance: 4 of the 5 automation/scripting/jobs endpoints (requestScriptingOptions, runScriptOnDevice, getActiveJobs, getDeviceActiveJobs) were cross-checked against an independently obtained copy of NinjaOne's OpenAPI spec. getAutomationScripts wasn't present in that copy (it's newer than that spec revision) — its exact /api path placement is inferred from the other 4's confirmed pattern, not independently verified. See the comment at the top of tools/automation.py.

• ninjaone_get_tickets filters client-side: NinjaOne's board-run endpoint's request schema defines filters/searchCriteria params, but the community wyre-technology project reports these 400 in practice — this tool always requests an unfiltered page and filters status/organization_id/device_id client-side instead.

• No single-ticket-get or standalone add-comment endpoint: NinjaOne's ticketing API doesn't expose a GET /ticketing/ticket/{id} — to look up one ticket, page through ninjaone_get_tickets on its board. Adding a comment isn't a separate endpoint either — it's folded into ninjaone_update_ticket's comment/comment_public params, alongside a PUT on the ticket itself.

• ninjaone_get_devices's df filter can be silently dropped by NinjaOne when scoping by organization (a known issue in the community project) — prefer ninjaone_get_organization_devices for an org-scoped device list.

• Architecture history: this server originally did its own OAuth2 exchange (took client_id/client_secret and called /oauth/token itself, per-request, never caching the result). That's since moved to the gateway — this server now only ever takes an already-exchanged bearer token (X-Ninja-Token) — matching the pattern MSPbots' gateway already uses for ms-graph-mcp/connectwise-asio-mcp. The gateway is responsible for the OAuth2 exchange and for refreshing tokens before their 1-hour expiry; if it doesn't, X-Ninja-Token/X-Ninja-User-Token requests will 401 against real NinjaOne endpoints (mapped to unauthorized here), not against this server's own logic.

• ninjaone_run_script_on_device uses a second, user-context token (X-Ninja-User-Token, gateway-exchanged via the refresh_token grant against a Web Application app) instead of the machine token every other tool uses — see the Overview section above for why. This is unverified against a real device/script so far; only the plumbing (missing-token error path, and a live call with a real machine-identity token reaching NinjaOne's real API and getting real data) has been checked.

• Verified against a live NinjaOne account: tools/list returns all 23 tools with clean schemas, pytest (17 tests) passes, and a real ninjaone_get_organizations call using a real, already-exchanged bearer token (via X-Ninja-Token) returned real organization data.