NinjaOne

NinjaOne MCP Server

A Model Context Protocol (MCP) server for interacting with NinjaOne, featuring a decision tree architecture for efficient tool loading.

One-Click Deployment

[!IMPORTANT] Before you click: this server depends on @wyre-ai/node-ninjaone, which is hosted on the GitHub Packages npm registry. GitHub Packages has no anonymous access — even though the package is public, every npm install needs a token. The cloud builder runs npm install for you, so you must give it one, or the build fails with npm error 401 Unauthorized ... npm.pkg.github.com.

1. Create a GitHub Personal Access Token with the read:packages scope (classic token). Any GitHub account works — you do not need to be a member of the wyre-ai org to read its public packages.
2. Add it as a build variable when prompted by the deploy flow:
   • Cloudflare Workers → set a build variable named NODE_AUTH_TOKEN to your PAT (Workers → Settings → Build → Variables and Secrets).
   • DigitalOcean App Platform → set an encrypted env var named GITHUB_TOKEN with scope Build Time to your PAT (the .do/app.yaml already declares it).

[!NOTE] Both targets run the full MCP server. DigitalOcean builds the Docker image and serves it over HTTP; Cloudflare Workers serves the same server via the SDK's Web Standard Streamable HTTP transport (src/worker.ts). After deploying, set your NinjaOne credentials as secrets — NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, and optionally NINJAONE_REGION — or set AUTH_MODE=gateway to take credentials per-request from X-Ninja-* headers. HTTP also requires CONDUIT_S2S_SECRET and a valid X-Gateway-S2S signature on /mcp (see HTTP authentication). The MCP endpoint is /mcp; /health is an unauthenticated liveness probe.

Architecture

This MCP server uses a hierarchical tool loading approach instead of exposing all tools upfront:

1. Navigation Phase: Initially exposes only a navigation tool (ninjaone_navigate)
2. Domain Selection: User selects a domain (devices, organizations, alerts, tickets)
3. Domain Tools: Server exposes domain-specific tools after selection
4. Lazy Loading: Domain handlers and the NinjaOne client are loaded on-demand

This architecture provides:

• Reduced cognitive load (fewer tools to choose from)
• Faster initial load times
• Better organization of related operations
• Clear navigation state

Installation

This package is published to the GitHub Packages npm registry, which requires a token even for public packages. Authenticate once, then install:

# 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-ai/ninjaone-mcp

The repo's .npmrc already points the @wyre-ai scope at GitHub Packages and reads the token from NODE_AUTH_TOKEN, so no further config is needed. The same applies to npx @wyre-ai/ninjaone-mcp below. Prefer a zero-setup option? Use the prebuilt container image (ghcr.io/wyre-ai/ninjaone-mcp) or the .mcpb bundle attached to each release.

Configuration

Copy .env.example and set the variables below.

/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include:

X-Gateway-S2S: t=<unix seconds>,v1=<hex>

v1 is HMAC-SHA256 of the ASCII string t=<unix seconds> (the same t= prefix that is sent in the header), keyed with CONDUIT_S2S_SECRET, and hex-encoded. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before any vendor credential is read. The secret value is never written to logs.

In AUTH_MODE=gateway, /mcp also requires X-Ninja-Client-ID and X-Ninja-Client-Secret (X-Ninja-Region is optional). Those headers are the only credential source for that request. A request missing them returns 401 and does not fall back to NINJAONE_CLIENT_ID / NINJAONE_CLIENT_SECRET.

MCP_ALLOW_INSECURE_DEV=1 skips the X-Gateway-S2S check for local development and forces the listener onto 127.0.0.1. A non-loopback MCP_HTTP_HOST, including 0.0.0.0, is ignored in that mode and the override is logged.

NinjaOne API Regions

Usage

Running Standalone

# 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-ai/ninjaone-mcp

Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "ninjaone": {
      "command": "npx",
      "args": ["@wyre-ai/ninjaone-mcp"],
      "env": {
        "NINJAONE_CLIENT_ID": "your-client-id",
        "NINJAONE_CLIENT_SECRET": "your-client-secret",
        "NINJAONE_REGION": "us"
      }
    }
  }
}

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode, NinjaOne credentials arrive on each request as X-Ninja-* headers; they are not read from the environment.

docker build -t ninjaone-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ninjaone-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset, defaults AUTH_MODE to gateway, publishes 127.0.0.1:8080:8080, and does not inject NINJAONE_CLIENT_ID or NINJAONE_CLIENT_SECRET:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses NINJAONE_CLIENT_ID and NINJAONE_CLIENT_SECRET:

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e NINJAONE_CLIENT_ID=your-client-id \
  -e NINJAONE_CLIENT_SECRET=your-client-secret \
  -e NINJAONE_REGION=us \
  -p 127.0.0.1:8080:8080 \
  ninjaone-mcp

Local HTTP without a secret is development-only. It binds 127.0.0.1 only and logs a warning:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Sign each /mcp request with X-Gateway-S2S as described in HTTP authentication. In gateway mode, also send X-Ninja-Client-ID and X-Ninja-Client-Secret.

Available Domains

Devices

Manage endpoints, reboot devices, view services and alerts.

Tools:

• ninjaone_devices_list - List devices, filterable by organization, device class, and online status. Paginated: a full page returns hasMore: true and a cursor to pass back for the next page.
• ninjaone_devices_get - Get device details
• ninjaone_devices_reboot - Schedule a device reboot
• ninjaone_devices_services - List Windows services on a device
• ninjaone_devices_alerts - Get device-specific alerts
• ninjaone_devices_activities - View device activity log
• ninjaone_devices_get_custom_fields - Get device custom fields
• ninjaone_devices_update_custom_fields - Update device custom fields

Organizations

Manage customer organizations and their resources.

Tools:

• ninjaone_organizations_list - List organizations
• ninjaone_organizations_get - Get organization details
• ninjaone_organizations_create - Create a new organization
• ninjaone_organizations_locations - List organization locations
• ninjaone_organizations_devices - List devices for an organization. device_class is sent upstream as df=class=<NodeClass> and applied to each page. The response is { devices, count, hasMore, cursor }, not a bare array.
• ninjaone_organizations_get_custom_fields - Get organization custom fields
• ninjaone_organizations_update_custom_fields - Update organization custom fields

Alerts

View and manage alerts across all devices.

Tools:

• ninjaone_alerts_list - List alerts with filters
• ninjaone_alerts_get - Get a single alert by UID (renders as an interactive card in MCP Apps hosts)
• ninjaone_alerts_reset - Reset/dismiss a single alert
• ninjaone_alerts_reset_all - Reset all alerts for a device or organization
• ninjaone_alerts_summary - Get alert count summary

Features:

• Interactive Alert Card (MCP Apps, SEP-1865): ninjaone_alerts_get renders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Reset alert" round-trip via ninjaone_alerts_reset; neutral by default, brandable via window.__BRAND__ injection or MCP_BRAND_* env vars; plain-JSON behavior is unchanged in other hosts

Tickets

Manage service tickets.

Tools:

• ninjaone_tickets_list - List tickets from a board (requires board_id; status/organization_id/device_id filters are applied client-side, see notes below)
• ninjaone_tickets_get - Get ticket details
• ninjaone_tickets_create - Create a new ticket (requires a ticket_form_id)
• ninjaone_tickets_update - Update an existing ticket's fields
• ninjaone_tickets_add_comment - Add a comment to a ticket
• ninjaone_tickets_comments - Get ticket log entries, optionally filtered by type
• ninjaone_tickets_boards_list - List ticket boards (to discover board_id values)
• ninjaone_tickets_forms_list - List ticket forms (to discover ticket_form_id values)
• ninjaone_tickets_form_get - Get one ticket form with its field definitions
• ninjaone_tickets_statuses_list - List the tenant's configured ticket statuses
• ninjaone_tickets_attributes_list - List ticket attribute (custom field) definitions
• ninjaone_tickets_contacts_list - List ticketing contacts (for requester_uid)
• ninjaone_tickets_users_list - List technicians, end users and contacts (for assignee_id)

Note: NinjaOne queries tickets per board, and board IDs vary by tenant — board 1 is not always the "All Tickets" board, so ninjaone_tickets_list requires an explicit board_id rather than silently guessing one. Discover IDs with ninjaone_tickets_boards_list.

Note: Ticket statuses, forms and attributes are configured per tenant. Read the real IDs with ninjaone_tickets_statuses_list, ninjaone_tickets_forms_list and ninjaone_tickets_attributes_list rather than assuming fixed names. priority is NONE/LOW/MEDIUM/HIGH — CRITICAL is a severity, not a priority.

Note: NinjaOne's board-run API cannot filter tickets by status, organization, or device server-side (attempting to throws a generic Bad request). ninjaone_tickets_list therefore applies those filters client-side within one board page. The response separates count (matches in this page) from scanned (tickets examined) and includes hasMore/cursor — page through until hasMore is false to get every match, and never treat a single page's count as a board-wide total. Status is matched against each ticket's status display name, so pass a name the tenant actually uses — ninjaone_tickets_statuses_list shows them.

Similarly, ninjaone_devices_list filters by organization_id through NinjaOne's dedicated per-organization endpoint (the general df=org device filter is unreliable and can silently return the full fleet). That endpoint documents no device-class query parameter. ninjaone_devices_list (when an organization is set) and ninjaone_organizations_devices still send device_class upstream as df=class=<NodeClass> (a named nodeClass parameter is ignored) and apply class and online filters to each page. count is matches in the page; keep paging while hasMore is true. device_class uses NinjaOne node classes (LINUX_WORKSTATION, VMWARE_VM_HOST, NMS_SWITCH, …) — LINUX, VMWARE_VM, and NMS are not valid.

Navigation Tools

Always available:

• ninjaone_navigate - Select a domain to work with
• ninjaone_status - Show current state and credential status
• ninjaone_back - Return to main menu (when in a domain)

Example 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.

Authentication

NinjaOne uses OAuth 2.0 for authentication. You need to:

1. Log in to your NinjaOne dashboard
2. Go to Administration > Apps > API
3. Create a new API application (application platform: API Services, grant type Client Credentials)
4. Grant it the scopes you need — see below
5. Note the Client ID and Client Secret
6. Configure the environment variables

The client library handles token refresh automatically.

OAuth scopes

By default the server requests monitoring management. Which scopes you actually need depends on what you use:

If your API app is granted fewer scopes than the default, set NINJAONE_SCOPES to match. NinjaOne rejects a token request that asks for a scope the app was never granted — it returns 400 invalid_scope rather than narrowing the grant — so the failure happens at the token exchange and every tool call fails, including reads. For a monitoring-only app:

export NINJAONE_SCOPES="monitoring"

Values may be comma- or space-separated and are case-insensitive. In gateway deployments the same value can be supplied per request via the X-Ninja-Scopes header.

License

Apache-2.0