Kaseya BMS

Kaseya BMS MCP Server

Kaseya BMS PSA API 用の Model Context Protocol（MCP）サーバーです。 チケット、アカウント、連絡先、契約、タイムエントリー、サービス カタログ、ナレッジベースを AI アシスタントに提供します。

ツール

ツール	説明
kaseya_bms_list_tickets	チケットを一覧表示します。省略可能な $filter を指定できます。省略した場合はステータスを選択します。
kaseya_bms_get_ticket	ID を指定してチケットを取得します。
kaseya_bms_create_ticket	新しいチケットを作成します（破壊的操作のため、確認が必要です）。
kaseya_bms_add_ticket_note	チケットにメモを追加します（破壊的操作のため、確認が必要です）。
kaseya_bms_list_time_entries	日付範囲でタイムエントリーを取得します（24h／7d／30d／カスタム／すべて）。
kaseya_bms_list_accounts	アカウント（クライアント）を取得します。
kaseya_bms_list_contacts	連絡先を取得します。
kaseya_bms_list_contracts	契約を取得します。
kaseya_bms_list_service_catalog	サービスカタログの項目を取得します。
kaseya_bms_search_knowledge_base	ナレッジベースを検索します。

ユーザーが必須のフィルターを省略した場合や、破壊的な操作を実行する場合、サーバーは MCP のエリシテーションを使って選択肢の提示や確認を行います。

インタラクティブなチケットカード（MCP Apps）

kaseya_bms_get_ticket は、MCP Apps ホスト （Claude Desktop／web）でインタラクティブなカードとして表示されます。カード内の「Add note」から kaseya_bms_add_ticket_note を介してメモを追加できます（常に内部専用として投稿されます）。それ以外のホストでは、プレーンな JSON の 動作に変更はありません。カードはデフォルトで中立的なデザインで、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）でブランド設定できます。再ビルドは 不要です。ui/ の編集後、npm run build:ui で埋め込みバンドルを再生成してください。

設定

.env.example をコピーしてください。Stdio と AUTH_MODE=env は Kaseya BMS の変数を読み取ります。ゲートウェイモードでは読み取りません。

変数	必須	説明
KASEYA_BMS_TENANT_SUBDOMAIN	Stdio および AUTH_MODE=env の場合	テナントのサブドメイン（例：yourcompany）
KASEYA_BMS_API_TOKEN	Stdio および AUTH_MODE=env で、いずれか一方が必要	BMS API トークン
KASEYA_BMS_K1_TOKEN	Stdio および AUTH_MODE=env で、いずれか一方が必要	Kaseya One SSO トークン
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	env（デフォルト）または gateway。ゲートウェイモードでは、各 /mcp リクエストに X-Kaseya-BMS-Tenant-Subdomain と X-Kaseya-BMS-API-Token または X-Kaseya-BMS-K1-Token が必要で、KASEYA_BMS_* へのフォールバックは行いません。
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_HTTP_HOST	いいえ	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定の場合は 0.0.0.0 が維持されます。これはコンテナーイメージで設定されている値であり、コンテナー内のすべてのインターフェイスでコンテナーがデプロイされるようにします。シークレットがない場合、開発用のバイパスでは代わりに 127.0.0.1 にバインドします。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。

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

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。値は t=<unix seconds>,v1=<hex> です。v1 は、CONDUIT_S2S_SECRET を鍵として、正確な文字列 t=<unix seconds> の HMAC-SHA256 を計算したものです（64 文字の小文字の 16 進数）。タイムスタンプはサーバーの時刻から 300 秒以内でなければなりません。ヘッダーがない、または無効な場合は 401 が返されます。シークレットがログに書き込まれることはありません。

import { createHmac } from "node:crypto";

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", process.env.CONDUIT_S2S_SECRET)
  .update(`t=${t}`)
  .digest("hex");
const xGatewayS2s = `t=${t},v1=${v1}`;

AUTH_MODE=gateway の場合、/mcp には X-Kaseya-BMS-Tenant-Subdomain と、X-Kaseya-BMS-API-Token または X-Kaseya-BMS-K1-Token のいずれかも必要です。これらのヘッダーだけが、そのリクエストの認証情報として使用されます。これらのヘッダーがないリクエストは 401 を返し、環境変数から KASEYA_BMS_* を読み取りません。リクエストごとに新しいサーバーインスタンスが作成され、認証情報は分離されます。

Docker Compose

チェックイン済みの Compose サービスはゲートウェイモードです。127.0.0.1:8080:8080 を公開し、CONDUIT_S2S_SECRET を必須とします。また、KASEYA_BMS_TENANT_SUBDOMAIN、KASEYA_BMS_API_TOKEN、KASEYA_BMS_K1_TOKEN、env_file は設定しません。イメージのビルドでは、GitHub Packages の認証情報を npmrc ビルドシークレットから読み取ります（リポジトリの .npmrc で設定するのはレジストリのみです）。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up --build

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

docker build -t kaseya-bms-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -e AUTH_MODE=env \
  -e KASEYA_BMS_TENANT_SUBDOMAIN=yourcompany \
  -e KASEYA_BMS_API_TOKEN=... \
  -p 127.0.0.1:8080:8080 \
  kaseya-bms-mcp

ローカル開発

npm install
npm run build
KASEYA_BMS_TENANT_SUBDOMAIN=yourcompany \
  KASEYA_BMS_API_TOKEN=... \
  npm start

HTTP は、CONDUIT_S2S_SECRET が実際のシークレットでない限り、起動を拒否します。

MCP_TRANSPORT=http CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" npm start
curl http://127.0.0.1:8080/health

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

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

ライセンス

Apache-2.0