Kaseya VSA

Kaseya VSA MCP サーバー

Kaseya VSA RMM API 用の Model Context Protocol（MCP）サーバーです。 管理対象エンドポイント、ソフトウェア／ハードウェアのインベントリ、パッチの状態、エージェント プロシージャ、アラーム、Service Desk チケット、組織、マシングループを AI アシスタントに公開します。

ツール

ツール	説明
kaseya_vsa_list_agents	管理対象エンドポイント（エージェント）を一覧表示します。$filter は任意です。
kaseya_vsa_get_agent	ID を指定してエージェントの詳細を取得します（MCP Apps ホストではインタラクティブカードとして表示されます）。
kaseya_vsa_get_software_inventory	エージェントにインストールされているソフトウェアを取得します。
kaseya_vsa_get_hardware_inventory	エージェントのハードウェア監査情報を取得します。
kaseya_vsa_get_patch_status	エージェントの保留中およびインストール済みのパッチを取得します。
kaseya_vsa_deploy_patches_now	エージェントにパッチを強制適用します（破壊的な操作のため、確認が必要です）。
kaseya_vsa_list_procedures	実行可能なエージェントプロシージャを一覧表示します。
kaseya_vsa_run_procedure	エージェントでプロシージャを実行します（破壊的な操作のため、確認が必要です）。
kaseya_vsa_list_alarms	未解決のアラームを一覧表示します（状態による絞り込みは任意です。指定がない場合は日付範囲を確認します）。
kaseya_vsa_list_tickets	Service Desk チケットを一覧表示します（SD モジュールが有効でない場合は、わかりやすいメッセージを返します）。
kaseya_vsa_list_organizations	テナント組織を一覧表示します。
kaseya_vsa_list_machine_groups	マシングループの階層を一覧表示します。

必須のフィルターが省略された場合や、破壊的な操作が実行された場合、サーバーは MCP の確認機能を使用して、選択肢の提示や確認を行います。

インタラクティブなデバイスカード（MCP Apps）

kaseya_vsa_get_agent は、MCP Apps ホスト（Claude Desktop/web）で読み取り専用のインタラクティブなデバイスカードとして表示され、 エンドポイント名、オンライン状態、組織、マシングループ、OS、IP アドレス、最終チェックイン日時を示します。カードはデフォルトでは中立的なデザインで、window.__BRAND__ の注入、または 配信時に適用される MCP_BRAND_* 環境変数（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、 MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、 MCP_BRAND_TEXT）でブランド設定できます。他のホストでのプレーンな JSON の動作に変更はありません。 ui/ を編集した後は、npm run build:ui を実行して埋め込みバンドルを再生成してください。

設定

.env.example をコピーし、以下の変数を設定してください。

変数	必須	説明
KASEYA_VSA_TENANT_URL	stdio および AUTH_MODE=env の場合	/api/v1.0 を含む完全なベース URL です。Compose ゲートウェイサービスでは読み込まれません。
KASEYA_VSA_USERNAME	stdio および AUTH_MODE=env の場合	ローカル認証のユーザー名（パスワードと併用）です。Compose ゲートウェイサービスでは読み込まれません。
KASEYA_VSA_PASSWORD	stdio および AUTH_MODE=env の場合	ローカル認証のパスワード（シークレット）です。Compose ゲートウェイサービスでは読み込まれません。
KASEYA_VSA_K1_TOKEN	stdio および AUTH_MODE=env の場合	Kaseya One SSO トークンです（ユーザー名とパスワードの代替）。Compose ゲートウェイサービスでは読み込まれません。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env（未設定時のコードのデフォルト）です。ゲートウェイモードでは、各 /mcp リクエストに X-Kaseya-VSA-* ヘッダーが必要で、KASEYA_VSA_* へのフォールバックは行われません。env では、S2S 認証が成功した後にのみこれらの変数が使用されます。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレットです。openssl rand -hex 32 で生成してください。未設定、または既知のプレースホルダー（changeme、your-s2s-secret、secret、placeholder、未解決の ${...} 値、および同様の公開例）の場合、HTTP サーバーはエラーをログに記録し、ゼロ以外の終了コードで終了します。これがないと Compose は起動しません。実際の値をコミットしないでください。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	ローカル開発時に限り、CONDUIT_S2S_SECRET なしで HTTP を起動するには、値を厳密に 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S を適用せず、MCP_HTTP_HOST がより広いアドレスでもリスナーを 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 です。

stdio および AUTH_MODE=env では、ユーザー名とパスワードの組み合わせ、または KASEYA_VSA_K1_TOKEN のいずれかが必要です。

/health は認証されていない状態のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。チェックは src/s2s-verify.ts の verifyS2sHeader で行われます。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET を鍵として、文字列 t=<unix seconds> をそのまま HMAC-SHA256 でハッシュした値（小文字の 16 進数 64 文字）です。タイムスタンプはサーバー時刻との差が 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報が読み取られる前に HTTP 401 が返されます。

AUTH_MODE=gateway の場合、/mcp には X-Kaseya-VSA-Tenant-Url に加えて、X-Kaseya-VSA-Username と X-Kaseya-VSA-Password の組み合わせ、または X-Kaseya-VSA-K1-Token も必要です。これらのヘッダーだけが、そのリクエストの認証情報ソースとなります。ヘッダーがないリクエストには 401 が返され、プロセス環境の KASEYA_VSA_* にはフォールバックしません。

受け付けられたリクエストごとに、分離された認証情報を持つ新しいサーバーインスタンスが作成されるため、テナント間で process.env が汚染されることはありません。

ローカル開発

npm install
npm run build
KASEYA_VSA_TENANT_URL=https://vsa.example.com/api/v1.0 \
  KASEYA_VSA_USERNAME=... \
  KASEYA_VSA_PASSWORD=... \
  npm start

HTTP は、CONDUIT_S2S_SECRET が設定されるまで起動を拒否します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start
curl http://127.0.0.1:8080/health

シークレットなしでのローカル HTTP は、開発時に限り使用できます。バインド先は 127.0.0.1 のみに制限され、警告がログに記録されます。ループバック以外の MCP_HTTP_HOST は無視され、上書きされたことがログに記録されます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

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

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

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。また、AUTH_MODE=gateway を設定し、静的な KASEYA_VSA_* 認証情報を注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、その後 KASEYA_VSA_* を使用します。

docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e KASEYA_VSA_TENANT_URL=https://vsa.example.com/api/v1.0 \
  -e KASEYA_VSA_USERNAME=... \
  -e KASEYA_VSA_PASSWORD=... \
  -p 127.0.0.1:8080:8080 \
  kaseya-vsa-mcp

ライセンス

Apache-2.0