NinjaOne

NinjaOne MCP サーバー

効率的なツール読み込みを実現する決定木アーキテクチャを採用し、NinjaOne と連携する Model Context Protocol（MCP）サーバーです。

ワンクリックデプロイ

重要

クリックする前にご確認ください： このサーバーは @wyre-ai/node-ninjaone に依存しており、 GitHub Packages npm レジストリでホストされています。GitHub Packages では匿名アクセスができません。 パッケージが公開されていても、npm install ごとにトークンが必要です。クラウドビルダーが npm install を実行するため、トークンを渡す必要があります。渡さないと、 npm error 401 Unauthorized ... npm.pkg.github.com が発生してビルドに失敗します。

1. read:packages スコープを持つ GitHub Personal Access Token を作成します （クラシックトークン）。 GitHub アカウントはどれでも構いません。公開パッケージの読み取りに wyre-ai 組織のメンバーである必要はありません。
2. デプロイフローで求められたら、ビルド変数としてトークンを追加します。
   • Cloudflare Workers → ビルド変数 NODE_AUTH_TOKEN に PAT を設定します （Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → 暗号化された環境変数 GITHUB_TOKEN を設定し、 スコープを Build Time にして PAT を指定します（.do/app.yaml ではすでに宣言されています）。

メモ

どちらのターゲットもフル MCP サーバーを実行します。DigitalOcean は Docker イメージをビルドして HTTP 経由で提供します。Cloudflare Workers は SDK の Web Standard Streamable HTTP トランスポート（src/worker.ts）を使って同じサーバーを提供します。デプロイ後、 NinjaOne の認証情報をシークレットとして設定してください。設定するのは NINJAONE_CLIENT_ID、NINJAONE_CLIENT_SECRET、 および任意の NINJAONE_REGION です。または、AUTH_MODE=gateway を設定して、リクエストごとに X-Ninja-* ヘッダーから認証情報を受け取ることもできます。HTTP ではさらに CONDUIT_S2S_SECRET と、 /mcp に対する有効な X-Gateway-S2S 署名が必要です（HTTP 認証を参照）。 MCP エンドポイントは /mcp です。/health は認証不要の稼働確認プローブです。

アーキテクチャ

この MCP サーバーでは、すべてのツールを最初から公開するのではなく、階層型のツール読み込み方式を採用しています。

1. ナビゲーションフェーズ：最初はナビゲーションツール（ninjaone_navigate）のみを公開します
2. ドメインの選択：ユーザーがドメイン（デバイス、組織、アラート、チケット）を選択します
3. ドメインツール：選択後、サーバーがドメイン固有のツールを公開します
4. 遅延読み込み：ドメインハンドラーと NinjaOne クライアントは、必要に応じて読み込まれます

このアーキテクチャにより、次のメリットが得られます。

• 認知負荷の軽減（選択するツールが少なくなります）
• 初回読み込みの高速化
• 関連する操作の整理が向上
• ナビゲーション状態が明確になります

インストール

このパッケージは GitHub Packages npm レジストリに公開されています。公開パッケージでもトークンが 必要です。認証を一度行ってからインストールしてください。

# 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

このリポジトリの .npmrc はすでに @wyre-ai スコープを GitHub Packages に向け、 NODE_AUTH_TOKEN からトークンを読み込むため、追加の設定は不要です。以下の npx @wyre-ai/ninjaone-mcp にも 同じことが当てはまります。セットアップなしですぐに使える方法をお探しですか？ビルド済み コンテナーイメージ（ghcr.io/wyre-ai/ninjaone-mcp）または各リリースに添付されている .mcpb バンドルをご利用ください。

設定

.env.example をコピーし、以下の変数を設定します。

変数	必須	説明
NINJAONE_CLIENT_ID	stdio および AUTH_MODE=env の場合	OAuth 2.0 クライアント ID
NINJAONE_CLIENT_SECRET	stdio および AUTH_MODE=env の場合	OAuth 2.0 クライアントシークレット
NINJAONE_REGION	いいえ	リージョン：us（デフォルト）、eu、oc、ca、us2、または fed
NINJAONE_SCOPES	いいえ	リクエストする OAuth スコープです。デフォルトは monitoring,management です。API アプリにより限定されたスコープが付与されている場合は設定してください。詳しくはOAuth スコープをご覧ください
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。Gateway モードでは、各 /mcp リクエストに X-Ninja-Client-ID と X-Ninja-Client-Secret が必要です。NINJAONE_* へのフォールバックは行いません。env は、S2S 認証に成功した後にのみこれらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレットです。HTTP サーバーは、この値が空か既知のプレースホルダーの場合、エラーをログに記録してゼロ以外の終了コードで終了します。Compose はこの値がないと起動しません。実際の値を決してコミットしないでください。openssl rand -hex 32 で生成できます。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET がない状態で HTTP を起動する場合に限り、ローカル開発用として 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみでバインドします。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレスです。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合にのみ適用されます。コンテナーイメージでは 0.0.0.0 が設定されています。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。

/health と /healthz は認証不要のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに次の情報を含める必要があります。

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

v1 は、ASCII 文字列 t=<unix seconds>（ヘッダーで送信されるものと同じ t= プレフィックス）を CONDUIT_S2S_SECRET をキーとして HMAC-SHA256 で署名し、16 進数でエンコードした値です。タイムスタンプはサーバーの時刻から 300 秒以内である必要があります。ヘッダーがないか無効な場合、ベンダーの認証情報を読み取る前に 401 を返します。シークレットの値がログに書き込まれることはありません。

AUTH_MODE=gateway の場合、/mcp には X-Ninja-Client-ID と X-Ninja-Client-Secret も必要です（X-Ninja-Region は任意です）。これらのヘッダーのみが、そのリクエストの認証情報として使用されます。ヘッダーがないリクエストは 401 を返し、NINJAONE_CLIENT_ID / NINJAONE_CLIENT_SECRET にはフォールバックしません。

MCP_ALLOW_INSECURE_DEV=1 はローカル開発用に X-Gateway-S2S の検証を省略し、リスナーを 127.0.0.1 に固定します。このモードでは、0.0.0.0 を含むループバック以外の MCP_HTTP_HOST は無視され、上書きされたことがログに記録されます。

NinjaOne API のリージョン

リージョン	ベース URL
us	https://app.ninjarmm.com
eu	https://eu.ninjarmm.com
oc	https://oc.ninjarmm.com
ca	https://ca.ninjarmm.com
us2	https://us2.ninjarmm.com
fed	https://fed.ninjarmm.com

使用方法

スタンドアロンで実行する

# 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 の設定

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

イメージはコンテナ内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、デフォルトでは AUTH_MODE=gateway になります。ポートをループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、NinjaOne の認証情報はリクエストごとに X-Ninja-* ヘッダーで渡され、環境変数からは読み込まれません。

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

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。また、AUTH_MODE はデフォルトで gateway になり、127.0.0.1:8080:8080 にポートを公開し、NINJAONE_CLIENT_ID や NINJAONE_CLIENT_SECRET は注入しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、NINJAONE_CLIENT_ID と 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

シークレットを使わないローカル HTTP は、開発専用です。127.0.0.1 のみでバインドし、警告をログに記録します。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

HTTP authentication の説明に従い、各 /mcp リクエストに X-Gateway-S2S を付けて署名してください。ゲートウェイモードでは、X-Ninja-Client-ID と X-Ninja-Client-Secret も送信してください。

利用可能なドメイン

デバイス

エンドポイントの管理、デバイスの再起動、サービスやアラートの表示を行います。

ツール：

• ninjaone_devices_list - デバイスを一覧表示します。組織、デバイスクラス、オンライン状態で絞り込めます。ページネーションに対応しています。1ページにすべての項目が収まらない場合は、hasMore: true と、次のページの取得時に渡す cursor が返されます。
• ninjaone_devices_get - デバイスの詳細を取得します
• ninjaone_devices_reboot - デバイスの再起動をスケジュールします
• ninjaone_devices_services - デバイス上の Windows サービスを一覧表示します
• ninjaone_devices_alerts - デバイス固有のアラートを取得します
• ninjaone_devices_activities - デバイスのアクティビティログを表示します
• ninjaone_devices_get_custom_fields - デバイスのカスタムフィールドを取得します
• ninjaone_devices_update_custom_fields - デバイスのカスタムフィールドを更新します

組織

顧客組織とそのリソースを管理します。

ツール：

• ninjaone_organizations_list - 組織を一覧表示します
• ninjaone_organizations_get - 組織の詳細を取得します
• ninjaone_organizations_create - 新しい組織を作成します
• ninjaone_organizations_locations - 組織の拠点を一覧表示します
• ninjaone_organizations_devices - 組織のデバイスを一覧表示します。device_class は df=class=<NodeClass> として上流に送信され、各ページに適用されます。レスポンスは { devices, count, hasMore, cursor } であり、配列のみではありません。
• ninjaone_organizations_get_custom_fields - 組織のカスタムフィールドを取得します
• ninjaone_organizations_update_custom_fields - 組織のカスタムフィールドを更新します

アラート

すべてのデバイスにわたるアラートを表示および管理します。

ツール：

• ninjaone_alerts_list - フィルターを指定してアラートを一覧表示します
• ninjaone_alerts_get - UID を指定して単一のアラートを取得します（MCP Apps ホストではインタラクティブカードとして表示されます）
• ninjaone_alerts_reset - 単一のアラートをリセットまたは解除します
• ninjaone_alerts_reset_all - デバイスまたは組織のすべてのアラートをリセットします
• ninjaone_alerts_summary - アラート数の概要を取得します

機能：

• インタラクティブなアラートカード（MCP Apps、SEP-1865）：ninjaone_alerts_get は、MCP Apps ホスト（Claude Desktop/web）でインタラクティブカードとして表示されます。カード内の「Reset alert」操作は ninjaone_alerts_reset を介してラウンドトリップします。デフォルトではニュートラルなデザインで、window.__BRAND__ の注入または MCP_BRAND_* 環境変数によってブランドに合わせて変更できます。他のホストでのプレーン JSON の動作は変更されません。

チケット

サービスチケットを管理します。

ツール：

• ninjaone_tickets_list - ボードのチケットを一覧表示します（board_id が必須です。status／organization_id／device_id のフィルターはクライアント側で適用されます。下記の注記を参照してください）
• ninjaone_tickets_get - チケットの詳細を取得します
• ninjaone_tickets_create - 新しいチケットを作成します（ticket_form_id が必須です）
• ninjaone_tickets_update - 既存のチケットのフィールドを更新します
• ninjaone_tickets_add_comment - チケットにコメントを追加します
• ninjaone_tickets_comments - チケットのログエントリーを取得します。type での絞り込みは任意です
• ninjaone_tickets_boards_list - チケットボードを一覧表示します（board_id の値を確認できます）
• ninjaone_tickets_forms_list - チケットフォームを一覧表示します（ticket_form_id の値を確認できます）
• ninjaone_tickets_form_get - フィールド定義を含むチケットフォームを 1 つ取得します
• ninjaone_tickets_statuses_list - テナントで設定されているチケットのステータスを一覧表示します
• ninjaone_tickets_attributes_list - チケット属性（カスタムフィールド）の定義を一覧表示します
• ninjaone_tickets_contacts_list - チケット管理の連絡先を一覧表示します（requester_uid 用）
• ninjaone_tickets_users_list - 技術者、エンドユーザー、連絡先を一覧表示します（assignee_id 用）

注記： NinjaOne はボードごとにチケットを照会し、ボード ID はテナントによって異なります。 ボード 1 が常に「すべてのチケット」ボードとは限らないため、ninjaone_tickets_list では ID を暗黙に推測せず、明示的な board_id が必要です。ID は ninjaone_tickets_boards_list で確認してください。

注記： チケットのステータス、フォーム、属性はテナントごとに設定されます。 固定の名前を想定せず、実際の ID を ninjaone_tickets_statuses_list、ninjaone_tickets_forms_list、 ninjaone_tickets_attributes_list で確認してください。priority は NONE／LOW／MEDIUM／HIGH です。CRITICAL は優先度ではなく severity です。

注記： NinjaOne のボード実行 API は、サーバー側でステータス、 組織、デバイスによるチケットの絞り込みができません（絞り込みを試みると、 汎用的な Bad request が返されます）。そのため、ninjaone_tickets_list は 1 つのボードページ内で、これらのフィルターを クライアント側で適用します。レスポンスでは count（このページ内の一致件数）と scanned（検査したチケット数）が分けて返され、hasMore／cursor も含まれます。 すべての一致を取得するには、hasMore が false になるまでページを取得してください。 また、単一ページの count をボード全体の合計として扱わないでください。ステータスは 各チケットのステータス表示名と照合されるため、テナントで実際に使われている名前を指定してください。 名前は ninjaone_tickets_statuses_list で確認できます。

同様に、ninjaone_devices_list は、NinjaOne 専用の組織ごとのエンドポイントを使って organization_id で絞り込みます（一般的な df=org デバイスフィルターは信頼性が低く、 すべてのデバイスを黙って返すことがあります）。このエンドポイントには、 デバイスクラスのクエリパラメーターがないことが記載されています。 ninjaone_devices_list（組織が設定されている場合）と ninjaone_organizations_devices は、引き続き device_class を df=class=<NodeClass> として 上流に送信します（名前付きの nodeClass パラメーターは無視されます）。また、 クラスとオンライン状態のフィルターは各ページに適用されます。count はそのページ内の一致件数です。 hasMore が true の間はページ取得を続けてください。device_class には NinjaOne のノードクラス （LINUX_WORKSTATION、VMWARE_VM_HOST、NMS_SWITCH、…）を使用します。 LINUX、VMWARE_VM、NMS は有効な値ではありません。

ナビゲーションツール

常に利用できます：

• ninjaone_navigate - 作業するドメインを選択します
• ninjaone_status - 現在の状態と認証情報の状態を表示します
• ninjaone_back - メインメニューに戻ります（ドメイン内にいる場合）

ワークフローの例

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.

認証

NinjaOne は OAuth 2.0 を認証に使用します。次の手順が必要です。

1. NinjaOne ダッシュボードにログインします
2. Administration > Apps > API に移動します
3. 新しい API アプリケーションを作成します（アプリケーションプラットフォーム：API Services、付与タイプ：Client Credentials）
4. 必要なスコープを付与します。下記を参照してください
5. Client ID と Client Secret を控えます
6. 環境変数を設定します

クライアントライブラリがトークンの更新を自動的に処理します。

OAuth スコープ

デフォルトでは、サーバーは monitoring management を要求します。実際に必要なスコープは、使用する機能によって異なります。

スコープ	必要となる操作
monitoring	すべての読み取り操作 — デバイス、組織、アラート、チケットの一覧表示
management	書き込み操作 — デバイスの再起動、アラートのリセット、チケットと組織の作成・更新
control	このサーバーでは使用しません

API アプリにデフォルトより少ないスコープが付与されている場合は、NINJAONE_SCOPES をそれに合わせて設定してください。 NinjaOne は、アプリに付与されていないスコープを要求するトークンリクエストを拒否し、許可範囲を狭めるのではなく 400 invalid_scope を返します。そのため、トークン交換時にエラーが発生し、読み取りを含むすべてのツール呼び出しが失敗します。監視専用アプリの場合：

export NINJAONE_SCOPES="monitoring"

値はカンマまたはスペースで区切ることができ、大文字と小文字は区別されません。ゲートウェイを使用するデプロイでは、X-Ninja-Scopes ヘッダーを使ってリクエストごとに同じ値を指定できます。

ライセンス

Apache-2.0