CIPP

CIPP MCP サーバー

CIPP（CyberDrain Improved Partner Portal）用のMCP（Model Context Protocol）サーバーです。AI アシスタントがCIPPのM365マルチテナント管理機能に構造化された形式でアクセスできるようにします。

特長

• 12カテゴリにわたる49個のツール
• テナント、ユーザー、グループ、メールボックスの管理
• テナント別またはユーザー別のメールボックスとオンラインアーカイブのサイズレポート
• ユーザー別のEntra IDサインインログ（ステータス、場所、条件付きアクセス、MFA）
• セキュリティ：条件付きアクセスポリシー、名前付きの場所、Microsoft Secure Score
• 標準とコンプライアンス：BPA、ドメインの正常性、ドリフト検出
• ライセンスレポート（テナント別およびCSP全体）
• アラート、監査ログ、スケジュール済みタスク
• GDAPのロールと招待の管理
• StdioおよびHTTPのトランスポートモード
• MCP Gatewayに対応

前提条件

• Node.js 18+
• 稼働中のCIPPデプロイメント
• CIPP API Key（CIPP Settings → API Client Managementから生成）

インストール

npm経由（公開後）

npx cipp-mcp

ソースから

git clone https://github.com/WYRE-AI/cipp-mcp
cd cipp-mcp
npm install
npm run build

設定

次の環境変数を設定します（または .env.example を .env にコピーします）。

変数	必須	説明
CIPP_BASE_URL	はい	CIPP の Azure Function App の URL（例：https://cippXXXXX.azurewebsites.net）です。SWA / フロントエンドの URL は使用しないでください。詳しくはFunction App の URL の確認方法を参照してください。
CIPP_API_KEY	いずれか1つ	静的な Bearer トークンです。これを使用するか、以下の OAuth 3 項目を使用してください。
CIPP_TENANT_ID	いずれか1つ	CIPP API クライアントのアプリ登録を所有する Entra テナント ID です。
CIPP_CLIENT_ID	いずれか1つ	CIPP の API Client Management ページで発行された OAuth クライアント ID です。
CIPP_CLIENT_SECRET	いずれか1つ	CIPP_CLIENT_ID に対応する OAuth クライアントシークレットです。
CIPP_TOKEN_SCOPE	いいえ	OAuth スコープを上書きします。既定値：api://<clientId>/.default。明示的に設定すると、以下のレガシースコープへのフォールバックが無効になります。
CIPP_TOKEN_SCOPE_FALLBACK	いいえ	スコープが明示的に設定されていない場合、CIPP が HTTP 401 を返したときに、レガシーの <clientId>/.default スコープで1回再試行し、このクライアントが受け入れるオーディエンスを再利用します。既定値：true。TOKEN_SCOPE_FALLBACK はエイリアスです。ゲートウェイリクエストでは x-token-scope-fallback を送信できます。
CIPP_TOKEN_URL	いいえ	OAuth トークンエンドポイントを上書きします（ソブリンクラウドのみ）。
MCP_TRANSPORT	いいえ	stdio（既定値）または http
AUTH_MODE	いいえ	env（stdio およびシングルテナント HTTP）または gateway。ゲートウェイモードでは、各 /mcp リクエストに CIPP 認証情報ヘッダーが必要で、CIPP_* へのフォールバックは行いません。コンテナーイメージと Compose のゲートウェイサービスでは gateway が設定されます。
CONDUIT_S2S_SECRET	HTTP では必須	ゲートウェイと共有するサービス間シークレットです。空、空白のみ、または既知のプレースホルダー（changeme、change-me、your-s2s-secret、your-secret、placeholder、secret、example、replace-me、replace-with-a-real-secret、s2s-secret、未解決の ${...} 値）の場合、HTTP はエラーを記録してゼロ以外のステータスで終了します。これがないと Compose は起動しません。実際の値を絶対にコミットしないでください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET がなくても HTTP を起動する場合は、ローカル開発に限り 1 を設定します。プロセスは警告を記録し、X-Gateway-S2S を強制せず、127.0.0.1 のみでリッスンします。ループバック以外の MCP_HTTP_HOST は無視され、その上書きがログに記録されます。このフラグによって既知のプレースホルダーが許容されることはありません。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http かつ CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定時は 127.0.0.1 が既定値です。コンテナーイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP モードのポート（既定値：8080）
LOG_LEVEL	いいえ	error、warn、info（既定値）、または debug

重要

CIPP_BASE_URL には、CIPP-API バックエンドの Azure Function App の URL (https://<function-app-name>.azurewebsites.net) を指定する必要があります。Static Web App / カスタムドメインの UI URL（例：https://cipp.yourdomain.com）は指定しないでください。SWA の組み込み 認証機能は Bearer トークンを横取りして、対話型ログインページにリダイレクトするため、 すべての API 呼び出しが失敗します。Azure Portal の CIPP リソースグループで、Function App （名前は cippXXXXX のような形式）を確認してください。

/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 をキーとして、ASCII 文字列 t=<unix seconds> の HMAC-SHA256 を16進数でエンコードしたものです。タイムスタンプはサーバーの時計とのずれが300秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、CIPP の認証情報を読み取る前に HTTP 401 が返されます。シークレットがログに書き込まれることはありません。

X-Gateway-S2S: t=1710000000,v1=<64 lowercase hex chars>

AUTH_MODE=gateway の場合、/mcp には x-base-url に加えて、x-api-key、または x-tenant-id、x-client-id、x-client-secret のすべてが必要です（x-token-scope、x-token-url、x-token-scope-fallback は任意です）。これらのヘッダーのみが、そのリクエストに対する CIPP 認証情報の取得元となります。必要なヘッダーがないリクエストには HTTP 401 が返され、プロセス環境の CIPP_* は使用されません。

AUTH_MODE=env でも有効な X-Gateway-S2S ヘッダーが必要で、その後、環境変数の CIPP_* が使用されます。

シークレットを設定しないローカル HTTP の使用は、開発用途に限られます。MCP_HTTP_HOST が 0.0.0.0 やほかのループバック以外のアドレスに設定されていても、127.0.0.1 にバインドされます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run dev

Docker

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

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

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。cipp-mcp サービスはゲートウェイモードで、AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開します。また、CIPP_API_KEY、CIPP_CLIENT_ID、CIPP_CLIENT_SECRET、CIPP_TENANT_ID、CIPP_BASE_URL、env_file は設定しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CIPP_BASE_URL=https://cippXXXXX.azurewebsites.net \
  -e CIPP_TENANT_ID=your-entra-tenant-id \
  -e CIPP_CLIENT_ID=your-client-id \
  -e CIPP_CLIENT_SECRET=your-client-secret \
  -p 127.0.0.1:8080:8080 \
  cipp-mcp

Claude Desktop での使用

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "cipp": {
      "command": "node",
      "args": ["/path/to/cipp-mcp/dist/entry.js"],
      "env": {
        "CIPP_BASE_URL": "https://cippXXXXX.azurewebsites.net",
        "CIPP_TENANT_ID": "your-entra-tenant-id",
        "CIPP_CLIENT_ID": "your-client-id",
        "CIPP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

注： CIPP_BASE_URL には Azure の Function App URL（.azurewebsites.net）を指定してください。フロントエンドの SWA URL（.azurestaticapps.net またはカスタムドメイン）ではありません。SWA ではブラウザー認証が強制され、すべての API リクエストが Microsoft のログインページにリダイレクトされます。

ツール

カテゴリ	ツール
テナント	list_tenants, get_tenant_details
ユーザー	list_users, create_user, edit_user, disable_user, reset_password, reset_mfa, revoke_sessions, offboard_user, bec_check, list_mfa_users, list_user_devices, list_user_groups, list_user_signin_logs
グループ	list_groups, create_group
メールボックス	list_mailboxes, list_mailbox_permissions, list_trusted_blocked_senders, list_mailbox_usage, get_mailbox_usage, set_out_of_office, set_email_forwarding
セキュリティ	list_conditional_access_policies, list_named_locations, get_secure_score, list_secure_score_controls
アプリケーション	list_enterprise_apps
標準	list_standards, run_standards_check, list_standard_templates, get_tenant_drift, get_tenant_alignment, create_standard_template, delete_standard_template, list_bpa, list_domain_health
ライセンス	list_licenses, list_csp_licenses
アラート	list_audit_logs, list_alert_queue
GDAP	list_gdap_roles, list_gdap_invites
スケジューラー	list_scheduled_items, add_scheduled_item
コア	ping, get_version, list_logs

作成直後のユーザーの編集

edit_user は、まずアカウントの現在の UPN を解決します。CIPP の Invoke-EditUser は呼び出しのたびに username + Domain から UPN を再構築するため、 UPN を指定せずに編集するとアカウント名が変更されてしまうためです。 Graph は作成直後のアカウントを認識するまで数秒かかる場合があります。そのため、検索で見つからない場合、HTTP 404 が返された場合、または本文が Graph の未検出エラーである 5xx（Request_ResourceNotFound コード、または Graph の「Resource '' does not exist or one of its queried reference-property objects are not present」というメッセージ）が発生した場合は、合計 4 回まで再試行し、 1 秒、3 秒、6 秒待ちます（約 10 秒）。再試行するかどうかの判定には HTTP ステータスを使用し、メッセージのテキストは使用しません。それ以外の 4xx （400、401、403）やその他の 5xx は再試行されません。最後までユーザーが見つからない場合、エラーには「Tried N times」と表示され、最後の試行で HTTP エラーが発生していた場合はそのステータスも表示されます。少し待ってから再試行してください。

メールボックスとアーカイブのサイズ

list_mailbox_usage は、テナント内のすべてのメールボックスについて、プライマリメールボックスのサイズ、アイテム数、クォータ、クォータに対する割合、およびオンラインアーカイブの同じ 4 項目を報告します。サイズの大きい順に並べられ、上位の行だけが返される場合でも、テナント内のすべてのメールボックスを対象とした合計が表示されます。

この機能を利用するには、対象テナントの CIPP レポートデータベースが同期されている必要があります。 これは設計上の制約です。Invoke-ListMailboxes の Exchange ライブクエリではサイズフィールドが一切選択されないため、キャッシュがテナント全体のサイズを取得できる唯一の情報源です。CIPP の Reports → Report Settings から同期してください。同期されていない場合、このツールは空の結果を返すのではなく、その旨を通知し、対処方法を示します。

get_mailbox_usage は、単一のメールボックスについて同じ情報を報告し、ライブで読み取るため、キャッシュは不要です。キャッシュが利用できない場合や古くなっている場合は、こちらを優先してください。

次の 2 点に注意してください。

• レポートで名前が非表示になっていると、テナント全体のサイズが空欄になります。 Microsoft 365 管理センターで Reports: conceal user, group, and site names が有効になっていると、Graph の使用状況レポートは UPN の代わりに 32 文字のハッシュを返します。そのため、CIPP がメールボックス一覧と突き合わせても一致するものがなく、すべてのメールボックスのキャッシュサイズが 0 になります。エラーではなく、テナントが空であるかのように表示されます。 list_mailbox_usage はこれを検出し、合計とともに警告を返します。 get_mailbox_usage には影響しません。Exchange 管理 API を直接読み取るためです。
• ユーザーごとの処理では、サイズがギガバイト単位で丸められます。 CIPP は返す前にギガバイト単位で小数点以下 2 桁に丸めるため、get_mailbox_usage のバイト数の精度は約 10 MB です。クォータは正確です。実際のバイト数を保持する生の Get-Mailbox 文字列から取得されます。

ユーザーのサインインログ

list_user_signin_logs は、1 人のユーザーの最新の対話型サインインを新しい順に返します。内容は、時刻、アプリ、IP アドレス、場所、成功または失敗（エラーコードと理由を含む）、クライアントアプリ、条件付きアクセスのステータスと評価されたポリシー、Graph が記録した認証方法（最初の要素を含む。MFA が必要だったかどうかは authenticationRequirement で確認できます）、デバイス、リスクが検出された場合はその情報です。また、失敗、重複のない IP アドレス、国の概要も含まれます。

• UPN またはオブジェクト ID を受け付け、必ず最初に解決します。 CIPP は userId で Graph をフィルターします。これは Entra オブジェクト ID です。UPN を指定すると一致するものがなく、「このユーザーは一度もサインインしていない」ように見える空のページが返されます。ユーザーを解決できない場合は空の結果ではなくエラーになります。
• 1 つのテナント、1 人のユーザー、1 ページに対応します。 top の既定値は 50、上限は 1000 です。ページが上限まで埋まっている場合、さらに古いサインインが存在する可能性を示す警告が表示されます。エンドポイントには全テナントを対象とする処理がないため、allTenants は拒否されます。テナント全体のサインインは CIPP の Sign-Ins レポート（ListSignIns）で確認できますが、このサーバーは公開していません。
• テナントに Entra ID P1/P2 が必要です。 これがないと Graph はサインインログ API へのアクセスを拒否します。このツールは一般的な「Failed to retrieve Sign In report」ではなく、ライセンスの不足を明示します。

Microsoft Secure Score

get_secure_score は、1 つのテナントの最新の Secure Score と直近の日次履歴を返します。list_secure_score_controls は推奨事項のカタログを返します。タイトル、ランク、最大ポイント、コスト、修復方法、脅威、およびサードパーティによる解決済みとしてのマーク、または無視する判断が含まれます。

CIPP には、Secure Score 専用の読み取りエンドポイントがありません。Secure Score の HTTP 関数は、コントロールを更新する ExecUpdateSecureScore だけであり、ここでは公開されていません。どちらのツールも、CIPP 独自の Secure Score ページと同じ ListGraphRequest を呼び出し、Endpoint に security/secureScores または security/secureScoreControlProfiles を設定します。

• 対象は 1 つのテナントです。 allTenants は拒否されます。CIPP の全テナントビューで使用されるのは、Graph へのライブ呼び出しではなく、夜間に更新されるスコアキャッシュです。これらのツールはそのキャッシュを読み取りません。
• ページネーションをオフにした場合にのみ、top で履歴の件数が制限されます。 ListGraphRequest は $top を Graph のページサイズとして扱い、NoPagination が設定されていない限り、すべての次のリンクをたどります。get_secure_score は常に両方を送信するため、top（既定値は 7、最大値は 90）が返される日次データの件数になります。コントロールカタログではページネーションが有効のまま、ページサイズは 999 に設定されているため、リスト全体が返されます。
• 結果が空でも、スコアが 0 という意味ではありません。 まだスコアが計算されていないテナント、または CIPP アプリに SecurityEvents.Read.All が付与されていないテナントでは、警告とともにデータがない状態が返されます。権限が拒否された場合は、汎用的な CIPP HTTP 400 ではなく、該当する Graph 権限が示されます。
• 比較対象は basis に基づいて照合されます。 「すべてのテナント」は AllTenants、「類似テナント」は TotalSeats です。これらの数値はすでにパーセンテージです。テナント自身のスコアの割合は currentScore / maxScore で、最大値が取得できない場合は 0% として報告せず、省略されます。

CIPP のバージョン互換性

リクエスト本文は CIPP 独自の Invoke-*.ps1 ハンドラーに合わせて構成されており、現在の CIPP と古いビルドのどちらでも動作するように作成されています。両者に違いがある場合は、サーバーはどちらでも受け付けられる形式で送信します。次の 3 つの動作に注意してください。

• offboard_user は完了ではなく、キューに追加されたことを報告します。 CIPP の ExecOffboardUser は、ジョブが作成された時点で HTTP 200 を返します。オフボーディングの結果を待つことも、報告することもありません。アカウントがオフボーディングされたと見なす前に、CIPP の Offboarding ビューで結果を確認してください。アクションが選択されていない場合、このツールは呼び出しを拒否します。そうしないと、何も実行せずに成功するジョブがキューに追加されるためです。
• 一部のエンドポイントは HTTP 200 でも失敗を報告します。 EditUser、AddScheduledItem、ExecOffboardUser は、エラーステータスではなく Results にエラーテキストを返します。これらのツールは Results を解析して status: "failed" を返すため、200 を成功と見なさないでください。
• 2 つのパラメーターには新しい CIPP が必要です。 offboard_user の DisableOneDriveSharing と set_out_of_office の timezone は、古いビルドではエラーにならず無視されます。そのため、DisableOneDriveSharing のみを選択したオフボーディングは、古い CIPP ではアクションを実行しません。

認証の設定

CIPP の API Client Management ページでは、Entra ID アプリ登録がプロビジョニングされ、OAuth の クライアント ID + クライアントシークレット（有効期間の長い Bearer トークンではありません）が発行されます。サーバーは OAuth 2.0 クライアント資格情報フローを使用して、リクエストごとにこれらの情報を短期間有効なアクセストークンと交換し、有効期限の直前までそのトークンをキャッシュします。

1. CIPP で、Settings → CIPP Settings → Integrations → CIPP-API に移動します
2. 新しい API クライアントを作成します
3. Client ID と Client Secret をコピーします。シークレットは後から取得できません
4. Function App URL を指定してサーバーを設定します（下記を参照）：

   CIPP_BASE_URL=https://cippXXXXX.azurewebsites.net
   CIPP_TENANT_ID=<your-entra-tenant-id>
   CIPP_CLIENT_ID=<client-id-from-cipp>
   CIPP_CLIENT_SECRET=<client-secret-from-cipp>
   

すでに静的な Bearer トークンをお持ちの場合（古い CIPP デプロイの場合）は、代わりに CIPP_API_KEY を設定し、OAuth 関連の変数は未設定のままにします。両方が指定されている場合は、CIPP_API_KEY が優先されます。

アクセストークンは api://<clientId>/.default を対象に要求されます。これは、CIPP の App Service 認証で許可される Application ID URI です。スコープに <clientId>/.default のみを指定して要求したトークンでは、aud がクライアント ID の GUID に設定されるため、App Service 認証で HTTP 401（本文は空）が返されます。この従来のオーディエンスを想定するデプロイにも自動的に対応します。明示的なスコープが設定されていない場合、401 が返されると、もう一方の自動オーディエンス（api://<clientId>/.default または <clientId>/.default）を使って一度だけ再試行します。成功したオーディエンスは、同じクライアントからの後続の呼び出しでも再利用されます。そのオーディエンスで後から 401 が発生した場合は、固定設定を解除してもう一方のオーディエンスを一度だけ試し、成功した方を再び記憶します。この再試行は、ほかのステータス（403、500 など）では実行されず、1 回のリクエストで複数回試行することもありません。スコープを固定するには CIPP_TOKEN_SCOPE を設定します。再試行を無効にするには CIPP_TOKEN_SCOPE_FALLBACK=false（別名 TOKEN_SCOPE_FALLBACK、ゲートウェイヘッダー x-token-scope-fallback）を設定します。

Function App URL の確認方法

CIPP は、Azure Function App をバックエンドとする Azure Static Web App（SWA）として実行されます。SWA の URL（カスタムドメインまたは *.azurestaticapps.net）ではブラウザー専用の認証が適用されるため、CIPP_BASE_URL として使用することはできません。代わりに Function App の URL を使用してください。

セルフホストの CIPP： Azure ポータルで Function App を確認します（SWA と同じリソースグループ内にある、Kind: functionapp の App Service を探します）。または、次を実行します：

az staticwebapp show --name <your-swa-name> --resource-group <rg> \
  --query "linkedBackends[0].backendResourceId" -o tsv

CIPP がホストする環境： ご利用のインスタンスの Function App URL について、CIPP チームにお問い合わせください。ブラウザーに表示される URL とは異なります。

IP 許可リスト

CIPP は、Azure Table Storage に保存されている IPRange フィールドを使って、各 API クライアントを検証します。サーバーのパブリック IP がこのリストに含まれていない場合、次のメッセージが返されます。

Access to this CIPP API endpoint is not allowed, the API Client does not have the required permission

セルフホスト： CIPP の UI（Settings → API Client Management）から IP を追加するか、CIPP ストレージアカウントの ApiClients テーブルに直接追加します。

CIPP がホストする環境： API クライアントの許可範囲にサーバーのパブリック IP を追加するよう、CIPP チームに依頼してください。

ライセンス

Apache-2.0 — LICENSE を参照してください

コントリビューション

Issue と PR を歓迎します。このサーバーは wyre-technology/msp-claude-plugins#24 に関連付けて管理されています。