ninjaone-mcp

NinjaOne RMM MCPサーバー — NinjaOneのPublic API v2（Organizations、Devices、Alerts、Ticketing、Automation/Scripting、Jobs）をMCPツールとして公開します。

NinjaOneとは / エージェントがこれを利用する場合

NinjaOneは、MSPがクライアントのIT資産を管理するために使用するRMM（リモート監視・管理）プラットフォームです。エージェントは、次のようなリクエストに対してこのMCPを利用します：

• 「この顧客はデバイスを何台持っていて、どのデバイスがオフラインですか？」 → ninjaone_get_organization_devices / ninjaone_get_devices

• 「このデバイス/組織にアクティブなアラートはありますか？」 → ninjaone_get_device_alerts / ninjaone_get_alerts

• 「サポートボードに開いているチケットは何ですか？」 → ninjaone_get_ticket_boards の後に ninjaone_get_tickets

• 「このデバイスでディスククリーンアップを実行して、完了したら教えてください」 → ninjaone_get_device_scripting_options で実行可能なものを確認し、ninjaone_run_script_on_device を実行し、ninjaone_get_device_active_jobs で完了を監視します

• 「利用可能な自動化スクリプトは何ですか？」 → ninjaone_get_automation_scripts

概要

このサーバーは、Model Context Protocol（Streamable HTTPトランスポート）を実装し、5つのグループにわたる23のツールを提供します。MSPbotsのVendor MCP Service SOPに従い、ステートレス、認証情報の保存なし、リクエストごとのヘッダー認証を実現しています。

これは、コミュニティのwyre-technology/ninjaone-mcpプロジェクトのツール面（organizations/devices/alerts/tickets）を出発点として、NinjaOneのNode SDKではなくREST APIに対して直接再実装し、さらにNinjaOne自身のOpenAPI 3.0.1仕様から取得した5つのautomation/scripting/jobsツールを追加したものです。以下のすべてのエンドポイントは、実際のNinjaOne API仕様に照らして確認済みであり、推測や二次情報からのコピーではありません。

NinjaOneはOAuth2 client_credentialsで認証します。NinjaOneの「API Services」OAuth2アプリのclient IDとsecretを、POST {base_url}/oauth/token で短期間有効なbearerトークンと交換します。このサーバーは、ツール呼び出しのたびにこの交換を自ら行い、トークン（またはclient_id/secret）を呼び出し間で保存・キャッシュすることはありません。

クイックスタート

Docker（推奨）

docker compose up --build

サーバーは http://localhost:8080 で起動します。

ローカル (uv)

uv sync
python -m ninjaone_mcp

ヘルスチェック

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

ヘルスチェックエンドポイントには認証情報は不要です。

認証パラメータ (Authentication)

/mcp へのすべてのリクエストには、次のHTTPヘッダーを含める必要があります：

必須ヘッダーのいずれかが欠けている場合は、401 Unauthorized を返します。

環境変数

base URL用の環境変数はありません。base URLは、リクエストごとに X-Ninja-Region ヘッダーから導出されます（config.py のリージョンテーブルを参照）。

MCPエンドポイント

POST http://localhost:8080/mcp

MCPクライアントを次の設定で接続します：

• トランスポート: http（Streamable HTTP）

• ヘッダー: X-Ninja-Client-Id、X-Ninja-Client-Secret（両方必須）、X-Ninja-Region（任意）

ツール一覧

テスト例 (Test Example)

チケットボードを一覧表示：

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

実行中のサーバーに対する同等の curl コマンド（Streamable HTTP MCPエンドポイント）：

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

デバイス上でスクリプトを実行：

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

APIリファレンス

• ドキュメント: https://app.ninjarmm.com/apidocs-beta/core-resources（eu/oc/ca/us2/fed の各リージョン相当）

• 認証: POST /oauth/token でのOAuth2 client_credentials グラント（grant_type、client_id、client_secret、scope）、スコープ: monitoring、management、control

既知のギャップ / 実装メモ

• エンドポイントの由来: 5つのオートメーション/スクリプティング/ジョブエンドポイント（requestScriptingOptions、runScriptOnDevice、getActiveJobs、getDeviceActiveJobs）のうち4つは、独自に入手したNinjaOneのOpenAPI仕様のコピーと照合済みです。getAutomationScriptsはそのコピーには含まれていません（その仕様改訂より新しいため）。その正確な/apiパスの配置は、他の4つの確認済みパターンから推測したものであり、独立に検証されたものではありません。tools/automation.pyの先頭にあるコメントを参照してください。

• ninjaone_get_ticketsはクライアント側でフィルタリングする: NinjaOneのボード実行エンドポイントのリクエストスキーマはfilters/searchCriteriaパラメータを定義していますが、コミュニティのwyre-technologyプロジェクトでは、これらのパラメータは実際には400を返すと報告されています。このツールは常にフィルタリングなしのページを要求し、代わりにstatus/organization_id/device_idをクライアント側でフィルタリングします。

• 単一チケット取得や独立したコメント追加エンドポイントは存在しない: NinjaOneのチケットAPIはGET /ticketing/ticket/{id}を公開していません — 1件のチケットを調べるには、そのボード上でninjaone_get_ticketsをページングして取得してください。コメントの追加も独立したエンドポイントではなく、ninjaone_update_ticketのcomment/comment_publicパラメータに組み込まれており、チケット自体へのPUTと併せて行われます。

• ninjaone_get_devicesのdfフィルタは、組織でスコープする場合にNinjaOneによって暗黙に無視される可能性があります（コミュニティプロジェクトで既知の問題）— 組織スコープのデバイス一覧にはninjaone_get_organization_devicesを推奨します。

• まだ実際の認証情報を使ったライブのNinjaOneアカウントではテストされていません — これまでに確認済みの内容: tools/listはクリーンなスキーマを持つ23個すべてのツールを返し、pytest（15テスト）が成功し、ダミーのclient_id/secretを使ったライブ呼び出しはNinjaOneの実際の本番/oauth/tokenエンドポイントに到達して、不正なリクエストエラーではなく実際の整形式の拒否応答（Client app not exist）を返しました — ベースURL、トークンエンドポイント、リクエスト形式が正しいことが確認できました。