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= (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= 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 sta