NinjaOne MCP サーバー

NinjaOne と連携するための Model Context Protocol (MCP) サーバーです。効率的なツール読み込みを実現する決定木アーキテクチャを備えています。

ワンクリックデプロイ

[!IMPORTANT] クリックする前に: このサーバーは @wyre-technology/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 を作成します (classic token)。 どの GitHub アカウントでも動作します — wyre-technology 組織のメンバーである 必要はありません。公開パッケージの読み取りには組織への所属は不要です。

2. デプロイフローで求められたら、ビルド変数として追加します:

   • Cloudflare Workers → NODE_AUTH_TOKEN という名前のビルド変数に PAT を設定します (Workers → Settings → Build → Variables and Secrets)。

   • DigitalOcean App Platform → GITHUB_TOKEN という名前の暗号化環境変数に Build Time スコープで PAT を設定します (.do/app.yaml で既に宣言されています)。

[!NOTE] どちらのターゲットも完全な 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-* ヘッダーから リクエストごとに認証情報を取得します。MCP エンドポイントは /mcp です。/health は 認証不要の liveness プローブです。

アーキテクチャ

この MCP サーバーは、すべてのツールを最初から公開する代わりに、階層的なツール読み込みアプローチを使用します:

1. ナビゲーションフェーズ: 最初はナビゲーションツール (ninjaone_navigate) のみを公開

2. ドメイン選択: ユーザーがドメイン (devices、organizations、alerts、tickets) を選択

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-technology/ninjaone-mcp

リポジトリの .npmrc は既に @wyre-technology スコープを GitHub Packages に向けており、 NODE_AUTH_TOKEN からトークンを読み取るため、追加の設定は不要です。これは以下の npx @wyre-technology/ninjaone-mcp にも同様に適用されます。セットアップ不要のオプションを お好みですか? プリビルドのコンテナイメージ (ghcr.io/wyre-technology/ninjaone-mcp) または 各 リリース に添付されている .mcpb バンドルを使用してください。

設定

以下の環境変数を設定します:

NinjaOne API リージョン

使用方法

スタンドアロンで実行

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

Claude Desktop の設定

Claude Desktop の claude_desktop_config.json に追加します:

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

Docker

docker build -t ninjaone-mcp .
docker run -e NINJAONE_CLIENT_ID=xxx -e NINJAONE_CLIENT_SECRET=xxx -e NINJAONE_REGION=us ninjaone-mcp

利用可能なドメイン

Devices (デバイス)

エンドポイントの管理、デバイスの再起動、サービスとアラートの表示。

ツール:

• ninjaone_devices_list - デバイスの一覧表示。組織、デバイスクラス、オンラインステータスでフィルタリング可能。ページネーション対応: 1 ページに全件が収まらない場合は hasMore: true と次のページ用の cursor が返されます。

• ninjaone_devices_get - デバイスの詳細を取得

• ninjaone_devices_reboot - デバイスの再起動をスケジュール

• ninjaone_devices_services - デバイス上の Windows サービスを一覧表示

• ninjaone_devices_alerts - デバイス固有のアラートを取得

• ninjaone_devices_activities - デバイスのアクティビティログを表示

Organizations (組織)

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

ツール:

• ninjaone_organizations_list - 組織の一覧表示

• ninjaone_organizations_get - 組織の詳細を取得

• ninjaone_organizations_create - 新しい組織を作成

• ninjaone_organizations_locations - 組織のロケーションを一覧表示

• ninjaone_organizations_devices - 組織のデバイスを一覧表示

Alerts (アラート)

すべてのデバイスにわたるアラートの表示と管理。

ツール:

• 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) でインタラクティブカードとして表示され、カード内の「アラートをリセット」ラウンドトリップが ninjaone_alerts_reset 経由で実行されます。デフォルトはニュートラルで、window.__BRAND__ の注入または MCP_BRAND_* 環境変数でブランド化可能。他のホストではプレーンな JSON 動作は変更されません。

Tickets (チケット)

サービスチケットの管理。

ツール:

• ninjaone_tickets_list - ボードからチケットを一覧表示 (board_id が必要。status/organization_id/device_id フィルターはクライアント側で適用されます。下記の注記を参照)

• ninjaone_tickets_get - チケットの詳細を取得

• ninjaone_tickets_create - 新しいチケットを作成

• ninjaone_tickets_update - 既存のチケットを更新

• ninjaone_tickets_add_comment - チケットにコメントを追加

• ninjaone_tickets_comments - チケットのコメントを取得

• ninjaone_tickets_boards_list - チケットボードを一覧表示 (board_id の値を見つけるため)

注記: NinjaOne はチケットをボード単位でクエリし、ボード ID はテナントごとに異なります — ボード 1 が常に「すべてのチケット」ボードであるとは限らないため、ninjaone_tickets_list は暗黙的に推測するのではなく、明示的な board_id を必要とします。ID は ninjaone_tickets_boards_list で見つけてください。そのエンドポイントが 404 を返すテナントでは、 NinjaOne の Web UI のボードリンクの URL から数値 ID を読み取ってください (例: 「すべてのチケット」サイドバーリンク)。

注記: NinjaOne のボード実行 API は、ステータス、組織、デバイスによるチケットの サーバー側フィルタリングができません (試行すると汎用の Bad request エラーが発生します)。 そのため ninjaone_tickets_list はこれらのフィルターを1 つのボードページ内でクライアント側で 適用します。レスポンスは count (このページ内の一致数) と scanned (調査したチケット数) を 分けて返し、hasMore/cursor も含みます — hasMore が false になるまでページをめくって すべての一致を取得してください。単一ページの count をボード全体の合計として扱わないでください。 ステータスは各チケットのステータス表示名と照合されるため、カスタムボードステータスは OPEN/IN_PROGRESS/WAITING/CLOSED の値にマップされない場合があります。

同様に、ninjaone_devices_list は NinjaOne の専用の組織別エンドポイントを通じて organization_id でフィルタリングします (一般的な df=org デバイスフィルターは 信頼性が低く、静かに全フリートを返すことがあります)。

ナビゲーションツール

常に利用可能:

• 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 を要求します。実際に必要なスコープは 使用内容によって異なります:

API アプリにデフォルトより少ないスコープしか付与されていない場合は、NINJAONE_SCOPES を一致するように設定してください。 NinjaOne はアプリに付与されていないスコープを要求する トークンリクエストを拒否します — 付与を絞り込むのではなく 400 invalid_scope を返します — そのため、トークン交換時に失敗し、すべてのツール呼び出しが失敗します。読み取り専用の アプリの場合:

export NINJAONE_SCOPES="monitoring"

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

ライセンス

Apache-2.0