entraadm MCP

entraadm-mcp

英語 | 日本語

Microsoft Entra ID のサインインと監査ログのトリアージに加え、朝の巡回で同じ認証情報を使って確認する Azure 側の 2 つの項目、Azure VM がバックアップされているか、Microsoft 365 自体に現在障害が発生しているかを確認する MCP サーバーです。読み取り専用ですが、侵害されたアカウントをすべての場所からサインアウトさせるオプトインのツールが 1 つあります。

Microsoft の公式 Microsoft MCP Server for Enterprise ではなく、これを選ぶ理由

Microsoft は、Entra ID のデータを扱う公式の MCP Server for Enterpriseを提供しています。キーボードを操作する管理者が対話的に使う用途には適していますが、無人のトリアージボットには適していません。

• 委任認証のみです。 公式サーバーはアプリ専用（クライアント資格情報）認証をサポートしていないため、サービスアカウントを使ったヘッドレス実行ができません。entraadm-mcp はその用途を想定しており、本番環境ではアプリ専用認証を使い、ローカル開発では委任認証（az login）にフォールバックします。
• 固定されたツールセットではなく、汎用の Graph クエリツールです。 公式サーバーは、Microsoft Graph に対する任意の GET 呼び出しやスキーマ検出呼び出しをモデルが構築できるツールを 1 つ公開しています。人間が使うには柔軟ですが、自動トリアージ用プロファイルで許可リストを設定するには扱いにくいものです。entraadm-mcp は、代わりに 15 個の固定された読み取り専用ツール（および以下で説明するオプトインの書き込みツール 1 つ）を公開します。
• AADSTS コードの説明がありません。 サインイン失敗は未加工のエラーコードとして返されるため、トリアージには引き続き対応表が必要です。entraadm-mcp は、すべてのサインイン失敗に、コードが実際に意味する内容を付記します。
• 複数のリクエストをまたいだ集計がありません。 Microsoft Graph 自体では、サインインを status/errorCode でサーバー側フィルタリングできず、パスワードスプレーを確認する組み込みのビューもありません。signin_failure_stats はクライアント側で集計し、多数の異なるユーザーに対するサインイン失敗がある IP を検出します。これは、Entra のアカウント単位のスマートロックアウトだけでは検出できないパターンです。

ツール

ツール	確認できる内容
health_check	Graph に接続できますか？ また、この認証情報でサインインログを読み取れますか？
get_user	このアカウントは有効ですか？ オンプレミスから同期されていますか？ ライセンスは何ですか？
signin_logs	このユーザーのサインインが失敗（または成功）した理由は何ですか？ AADSTS コードを翻訳して表示します。
signin_failure_stats	テナント全体の失敗の集計：上位のエラーコード、ユーザー、アプリ、送信元 IP、パスワードスプレーの疑いがある対象
signin_success_stats	送信元 IP ごとのテナント全体の成功の集計：複数のアカウントが共有する IP、レガシー認証（SMTP/IMAP）での成功 — 侵害の発見に役立つビュー
compromise_suspects	乗っ取られた可能性が高いアカウント：多数のアカウントにパスワードスプレーを試み、その一部への侵入に成功した外部 IP（spray_breaches）、居住国以外からの成功（レガシープロトコル経由の場合は高リスク）（foreign_successes）、およびテナントに Entra ID P2 がある場合は Microsoft 独自のリスクユーザー
signin_by_ip	1 つの送信元 IP からのすべてのサインイン：その IP から誰がサインインできたか、誰が試行されたか、いつ行われたか
directory_audits	ディレクトリで誰が何を（ブロック／ブロック解除、属性の編集）いつ変更したか
get_user_auth_methods	このアカウントには MFA が実際に登録されていますか？
list_subscriptions	この認証情報で確認できる Azure サブスクリプションはどれですか？（ARM）
vm_backup_status	Azure Backup でバックアップされている Azure VM はどれですか？ 最後のバックアップは成功しましたか？ 古い復旧ポイントはありますか？（ARM）
vm_backup_policies	Azure VM バックアップポリシーのスケジュールと保持期間はどのようになっていますか？（ARM）
vm_activity	この Azure VM を誰かが再起動しましたか？ それとも Azure によるもの（ホスト障害、メンテナンス）ですか？ 指定期間のアクティビティログと Resource Health を確認します（ARM）
m365_service_health	Microsoft 365 サービスは低下していますか？ 未解決のインシデントとアドバイザリはどれですか？
daily_brief	m365_service_health、signin_failure_stats、directory_audits、compromise_suspects を組み合わせた 1 回の呼び出しによる概要（件数と上位 5 件）

上記のすべてのツールは読み取り専用です。状態を変更するツールが 1 つありますが、既定では無効です。

ツール	機能
revoke_sign_in_sessions	1 つのアカウントをすべての場所でサインアウトさせます（Graph の revokeSignInSessions：更新トークンとセッション Cookie が無効になります）。侵害が確認された場合に使用します。ENTRAADM_ENABLE_REVOKE_SESSIONS=1 の場合にのみ登録されます

まず正確な userPrincipalName でアカウントを検索し、ゲストの場合は拒否します。すべての結果で、revoked と not_covered を含む同じキーが返されます。このツールはアカウントを無効にしたり、パスワードをリセットしたり、MFA の方法を削除したりしません。また、発行済みのアクセストークンは有効期限が切れるまで（通常は約 1 時間）引き続き使用できます。Graph が確認した場合、revoked は true になります。何も実行されなかった場合（拒否、リクエスト送信前の期限切れ、Graph からの 4xx）は false になります。結果が不明な場合（ネットワークエラーによる応答の消失、再試行後の 5xx、リクエスト送信後の期限切れ、読み取り不能な成功応答）は null になります。この場合は再度呼び出しても安全です。取り消しは冪等です。独自の承認ステップを設けていないデプロイメント（共有ゲートウェイなど）では、このスイッチを未設定のままにしてください。その場合、このツールは tools/list に表示されません。アカウントのブロック解除とパスワードのリセットは対象外です。

4 つの Azure Resource Manager ツールが Entra という名前のサーバーにあるのは意図的です。同じアプリ登録と同じ azure-identity 認証情報オブジェクト（2 つ目のトークンスコープ、https://management.azure.com/.default）を使用し、同じデプロイメントで実行され、同じ health_check の対象となります。これらのツール用に別のサーバーを用意すると、運用対象が倍増します。これらはリソース管理ではなくガバナンスの読み取りです。認証情報に Reader ロールが割り当てられていないサブスクリプションは、list_subscriptions に表示されません。

認証モデル

環境変数の設定状況に応じて、2 つの認証モードが選択されます。

モード	条件	環境変数
app-only	3 つすべてが設定されている	ENTRAADM_TENANT_ID、ENTRAADM_CLIENT_ID、ENTRAADM_CLIENT_SECRET
azure-cli	どれも設定されていない	（現在の az login セッションを使用）

app-only 用の 3 つの環境変数のうち 1 つまたは 2 つだけを設定すると、設定エラーとなり、サーバーは起動を拒否します。意図した認証モードとは異なるモードに黙ってフォールバックすることはありません。

必要な Graph のアクセス許可

ツール	アクセス許可	備考
get_user（基本フィールド）	User.Read.All
signin_logs、signin_failure_stats、signin_success_stats、compromise_suspects、signin_by_ip、directory_audits、get_user の sign_in_activity フィールド	AuditLog.Read.All（app-only）または レポート閲覧者 ディレクトリロール（委任）
get_user_auth_methods	UserAuthenticationMethod.Read.All	app-only のみ。一般的なテナントのロール割り当てでは、委任認証（az login）で利用できません
m365_service_health、daily_brief の service_health セクション	ServiceHealth.Read.All	委任認証では、サインイン中のユーザーにもサービスの正常性を閲覧できる Entra ロール（サービス サポート管理者やグローバル閲覧者など）が必要です
compromise_suspects の microsoft_risky_users、identity_protection プローブ（health_check、daily_brief）	IdentityRiskyUser.Read.All	オプションです。Identity Protection には Entra ID P2 が必要です。これがない場合、Graph は 403「ライセンスがありません」を返し、プローブは not_licensed を報告します。それ以外に変更はありません
revoke_sign_in_sessions（オプトイン）	User.RevokeSessions.All（app-only）または ユーザー管理者／ヘルプデスク管理者 ディレクトリロール（委任。管理者アカウントの場合は 特権認証管理者）	ENTRAADM_ENABLE_REVOKE_SESSIONS=1 の場合のみです。書き込みアクセス許可です。このツールを必要とするデプロイにのみ付与してください。事前のアカウント検索には User.Read.All が必要です。このアクセス許可がない場合、ツールは使用中の認証モードに対して missing_permission を返し、何も変更しません

必要な Azure RBAC

ツール	ロール	備考
list_subscriptions	なし	資格情報で参照できるものをすべて一覧表示します。空のリストは、まだどこにもロールが付与されていないことを意味します
vm_backup_status、vm_backup_policies、vm_activity	各サブスクリプションの Reader	Reader は */read で、使用するすべてのエンドポイントをカバーします。Backup Reader だけでは不十分です（Microsoft.Compute/virtualMachines/read がありません）。サービスプリンシパル（アプリのみ）またはサインイン済みユーザー（azure-cli）に付与します

Azure RBAC は任意です。health_check は ARM への到達性と、参照可能なサブスクリプション数を情報提供用の arm プローブとして報告しますが、status は変更しないため、Entra のトリアージのみを目的とするデプロイは healthy のままです。

アクセス許可が不足していても、ツールがクラッシュすることはありません。そのツール（または該当フィールド）の結果は {"error": "...", "missing_permission": "..."} となり、必要なロールまたはアクセス許可を人が読める形で説明します。そのため、完全なアクセス許可が付与される前でも、health_check を含むすべてのツールを引き続き利用できます。

Identity Protection（Entra ID P2）。 compromise_suspects は、テナントで利用可能な場合に Microsoft 独自のリスク判定を追加します。低コストの riskyUsers?$top=1 プローブで各テナントを分類します。licensed、not_licensed（403「not licensed」：Entra ID P2 なし）、no_permission（その他の 403：IdentityRiskyUser.Read.All なし）、または error です。licensed と not_licensed は 1 時間キャッシュされます（行の riskLevel: hidden を示す 200 応答も、P2 がないことを意味します）。エンドポイント自体もプローブします。/subscribedSkus は拒否される可能性があり、SKU の一覧を取得できても P2 への対応付けが必要です。health_check は status を変更せずにテナントごとに報告し、daily_brief の概要もテナントごとに報告するため、P2 が有効になった日を把握できます。ライセンスがある場合、microsoft_risky_users は高リスクの未解決ユーザー（atRisk / confirmedCompromised）と、中リスクのユーザーを別々に一覧表示し、spray_breaches / foreign_successes にも含まれるユーザーに印を付けます。その場合、counts はリストを切り詰める前にすべての検出結果から重複を除いたアカウント数です。high はこのツールまたは Microsoft の高リスクリストのいずれかで高リスクとされたアカウント数、medium はこのツールまたは Microsoft の中リスクリストで中リスクとされ、かつ高リスクではないアカウント数です（counts.microsoft_high / microsoft_medium は Microsoft の各リストの件数を示します）。それ以外の場合、このセクションは {available: false, reason} となり、ほかの内容は変わりません。「リスクのあるユーザーはいない」と解釈しないでください。

セットアップ

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

設定

本番環境や無人実行では、アプリ専用の変数を 3 つ設定します。

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

または、ローカル開発では 3 つとも未設定のままにして、先に az login を実行します。

任意：

# Default page cap for the log-scanning tools (1-50, default 50).
export ENTRAADM_MAX_PAGES_DEFAULT=50
# Wall-clock budget per tool call in seconds (default 45; 0 disables). A hosted MCP
# client cuts a call off at about 60 s, so a scan stops at the budget and returns
# what it has with capped=true.
export ENTRAADM_DEADLINE=45
# Your own address ranges (NAT egress, offices, labs). Spray suspects inside them are
# listed separately as internal_spray_suspects, labelled with the site.
export ENTRAADM_SITES_INI=/path/to/sites.ini
# The countries your users sign in from (assigned ISO 3166-1 alpha-2 codes). compromise_suspects
# reports successes from elsewhere; unset or with an invalid code, that list is skipped.
export ENTRAADM_HOME_COUNTRIES=JP
# Register revoke_sign_in_sessions, the one state-changing tool (exactly "1"; anything
# else leaves it off). Also needs the User.RevokeSessions.All permission.
export ENTRAADM_ENABLE_REVOKE_SESSIONS=1
# Serve several tenants from one process (see "Several tenants" below).
export ENTRAADM_CONFIG=/path/to/tenants.ini

ENTRAADM_SITES_INI は、keycloak-mcp の KEYCLOAK_SITES_INI と同じ形式を使用するため、1 つのファイルを両方で使用できます（sites.ini.example を参照）。検索では最長のプレフィックスが優先されます。ファイルが設定されているものの読み込めない場合、health_check は degraded を報告し、すべての IP が外部として扱われます。無効な CIDR も同様に報告されますが、有効な範囲は引き続き使用されます。

複数のテナント

gwsadm-mcp が複数の Workspace ドメインに対応するのと同様に、1 つのプロセスで複数の Entra テナントに対応できます。ENTRAADM_CONFIG に、テナントごとに 1 つの [tenant.<name>] セクションを含む INI ファイルを指定します。

[tenant.staff]
tenant_id = 00000000-0000-0000-0000-000000000001
domains = example.edu
default = true

[tenant.students]
tenant_id = 00000000-0000-0000-0000-000000000002
domains = students.example.edu
; optional: an app registration of its own instead of the shared one
; client_id = 00000000-0000-0000-0000-000000000003
; client_secret_env = ENTRAADM_STUDENTS_CLIENT_SECRET

キー	必須	意味
tenant_id	はい	テナントの ID（GUID）、またはそのドメイン名（ドットを含むもの。例：contoso.onmicrosoft.com）。common、organizations、consumers は拒否されます
domains	はい	このテナントにルーティングする UPN ドメインをカンマ区切りで指定します（大文字・小文字を区別しない完全一致）
default	複数ある場合はいずれか 1 つのセクションで必須	呼び出しでテナントが指定されていない場合に使用するテナントです。セクションが 1 つだけの場合は、それが既定値になります
client_id + client_secret_env	いいえ。両方指定するか、両方とも指定しない	独自のアプリを指定します。client_secret_env にはシークレットを格納する環境変数名を指定します。ファイルにシークレットを記述しないでください
client_id のないセクションでは、環境変数のアプリ（ENTRAADM_CLIENT_ID /
ENTRAADM_CLIENT_SECRET）を再利用し、そのセクションのテナントからトークンを要求します。環境変数のアプリがない場合は、そのテナントで az login を使用します。ENTRAADM_CONFIG が設定されている場合、ENTRAADM_TENANT_ID
は使用されません。ENTRAADM_CONFIG の設定を解除すれば、上記のシングルテナント構成は変更されません。

1 つのアプリを複数のテナントで共有するには、アプリ登録をマルチテナント（サポートされるアカウントの種類: 任意の組織ディレクトリ内のアカウント）にし、同じ Graph アプリケーション権限を追加してから、他の各テナントの管理者に管理者の同意を付与してもらいます。

https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<app-id>

ファイルが読み取り不能な場合、[tenant.*] 以外のセクションや不明なキーがある場合、tenant_id または domains がない場合、tenant_id が GUID でもドット区切りドメインでもない場合、1 つのドメインが 2 つのテナントに割り当てられている場合、または複数のテナント間でデフォルトがない（あるいは 2 つある）場合、サーバーは起動を拒否し、--check は失敗します。--check はすべてのテナントを検査します。

ルーティング：

• UPN を受け取るツール（get_user、get_user_auth_methods、signin_logs、 revoke_sign_in_sessions、および user が指定された場合の directory_audits）は、UPN のドメインが domains に含まれるテナントで動作します（完全一致）。どのテナントも要求していないドメインの場合は例外ではなく拒否され、tenant_configured: false、 found: null（検索は実行されません）、および configured_domains が返されます。revoke_sign_in_sessions の場合は、revoked: false、found: null となり、何も送信されません。このような UPN を頻繁に検索する場合は、<tenant>.onmicrosoft.com を domains に追加してください。
• get_user、get_user_auth_methods、signin_logs は tenant も受け取ります。これは UPN のドメインより優先されます。*.onmicrosoft.com または #EXT# の UPN、あるいはサインインがホストテナントに記録される B2B ゲストに使用します。 revoke_sign_in_sessions には意図的にこの上書き機能がありません。書き込み先は常に、UPN のドメインを所有するテナントだけです。
• テナント全体を対象とするツール（signin_failure_stats、signin_success_stats、compromise_suspects、 signin_by_ip、directory_audits、m365_service_health）は省略可能な tenant を受け取り、デフォルトのテナントが使用されます。tenant と、ドメインを別のテナントが要求する user の両方を指定した directory_audits は拒否されます（誤ったログを検索して何も見つからないためです）。どのテナントも要求していないドメインの user（外部またはパートナーの管理者、ゲスト）は、指定されたテナントまたはデフォルトのテナントで検索され、結果には user_domain_claimed: false と示されます。
• tenant はセクション名、そのテナントのドメイン、またはテナント ID です。テナントファイルがない場合は default または環境変数のテナント ID を指定できます。それ以外は拒否されます（tenant_configured: false）。
• health_check と daily_brief はすべてのテナントを対象とします。トップレベルのキーはこれまでどおりデフォルトのテナントのものです。tenant はそのテナントを示し、tenants にはテナントごとの結果が格納されます。呼び出しの予算（ENTRAADM_DEADLINE）はテナント間で均等に分割されます（デフォルトが最初で、残り時間を各テナントに順次割り当てます）。そのため、応答の遅いテナントが他のテナントを停止させることはありません。応答しないテナントはそのエントリで error となり、health_check の status は最大でも degraded になります。ENTRAADM_DEADLINE=0 の場合、予算はなく、各テナントが順番に全件スキャンされるため、クライアントの約 60 秒のタイムアウトを超えることがあります。
• Azure Resource Manager ツール（list_subscriptions、vm_backup_status、 vm_backup_policies、vm_activity）はデフォルトのテナントのみを対象とします。
• テナントファイルがある場合、すべての結果に tenant が含まれます（ARM ツールの場合はデフォルトのテナント、対象テナントを選べなかった拒否の場合は null）。環境変数のみを使う場合の結果は変更されません。ただし、revoke_sign_in_sessions には常に tenant、tenant_configured、configured_domains が含まれます（キーは変わりません）。

使用方法

Claude Code（プラグイン）

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code（手動）

.mcp.json に追加します：

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

Codex

codex mcp add entraadm-mcp \
  --env ENTRAADM_TENANT_ID=your-tenant-id \
  --env ENTRAADM_CLIENT_ID=your-client-id \
  --env ENTRAADM_CLIENT_SECRET=your-client-secret \
  -- uvx entraadm-mcp

stdio サーバーを起動する他の MCP クライアントも同じ方法で動作します。コマンドとして uvx entraadm-mcp を指定し、環境内で Configuration の ENTRAADM_* 変数を設定してください。

直接実行

entraadm-mcp

CLI オプション

オプション	効果
--version	バージョンを表示して終了します
--check	認証情報を解決し、Graph の到達可能性とサインインログへのアクセスを調査して、レポート（情報提供用の ARM 行を含む）を表示し、終了コード 0 で終了します（設定エラーの場合は 1）

注意事項

• カバレッジの契約。 ページ分割された Graph コレクションを走査する各結果には、ウィンドウ全体を走査できなかった場合、capped のブール値が含まれます。部分的な走査を網羅的な結果として報告することはありません。
• found: false はエラーではありません。 get_user と get_user_auth_methods は、存在しないアカウントに対して error キーではなく {"found": false, ...} を返します。ユーザーの userPrincipalName の入力ミスによって、このサーバーが壊れているように見えることはありません。
• 保持期間。 Entra ID P1 では、サインインログとディレクトリ監査ログが 30 日間保持されます。この期間を超えるウィンドウでは、エラーではなく空の結果が返されます。

開発

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

ライブスモークテスト

uv run python scripts/smoke_test.py

読み取り専用です（有効になっていても、名前により revoke_sign_in_sessions はスキップされます）。ペイロードは出力されず（ツール名、ステータス、行数のみ）、範囲も制限されています（小さく明示的なウィンドウとページ上限を使用）。テナントへの書き込みや、1 日を超えるログのスキャンは行いません。

リリース

このリポジトリでは、Conventional Commits に基づく release-please を使用しています。feat:／fix: の PR を main にマージすると、release-please がリリース PR を作成（または更新）します。その PR をマージするとリリースにタグが付けられ、公開パイプライン（PyPI、MCP Registry）が実行されます。

ライセンス

MIT