entraadm-mcp

English | 日本語

Microsoft Entra IDのサインインおよび監査ログのトリアージのためのMCPサーバー。読み取り専用。

公式のMicrosoft MCP Server for Enterpriseではなくこれを使う理由

MicrosoftはEntra IDデータ用の公式MCP Server for Enterpriseを提供しています。これはキーボードの前で操作する管理者には適していますが、無人で動作するトリアージボットには適していません：

• 委任認証のみ。 公式サーバーはアプリ専用（クライアント資格情報）認証をサポートしていないため、サービスアカウントの背後でヘッドレスに実行できません。entraadm-mcpはそのケース向けに構築されています：本番ではアプリ専用、ローカル開発では委任（az login）フォールバックを使用します。

• 固定ツールセットではなく、汎用のGraphクエリツール。 公式サーバーは、モデルがMicrosoft Graphに対して任意のGET/スキーマ探索呼び出しを構築できる1つのツールを公開しています。これは人間にとっては柔軟ですが、自動化されたトリアージプロファイルの許可リストの背後に置くのは厄介です。entraadm-mcpは代わりに7つの固定された読み取り専用ツールを公開します。

• AADSTSの翻訳なし。 サインイン失敗は生のエラーコードとして返されます。トリアージには依然としてルックアップテーブルが必要です。entraadm-mcpはすべてのサインイン失敗に、コードが実際に意味することを注釈として付けます。

• リクエスト間の集約なし。 Microsoft Graph自体はサーバー側でstatus/errorCodeによるサインインのフィルタリングができず、組み込みのパスワードスプレー表示もありません。signin_failure_statsはクライアント側で集約し、多数の異なるユーザーに対するサインイン失敗があるIPにフラグを立てます — Entraのアカウントごとのスマートロックアウトだけでは捕捉できないパターンです。

Related MCP server: Microsoft Graph MCP Server

ツール

すべてのツールは読み取り専用です。書き込み操作（アカウントのブロック解除、パスワードのリセット、セッションの失効）はこのサーバーの対象外です。

認証モデル

設定された環境変数によって選択される2つの認証モード：

3つのアプリ専用変数のうち1つまたは2つだけを設定することは設定エラーであり、意図したものとは異なる認証モードに黙ってフォールバックするのではなく、サーバーは起動を拒否します。

必要なGraph権限

権限が不足していてもツールがクラッシュすることはありません。そのツール（またはその1つのフィールド）は、必要なロールまたは権限の人間が読める説明とともに{"error": "...", "missing_permission": "..."}に縮退し、完全な権限が付与される前でもhealth_checkおよび他のすべてのツールが使用可能な状態を維持します。

セットアップ

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 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

使用方法

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:-}"
      }
    }
  }
}

直接実行

entraadm-mcp

CLIオプション

注意事項

• カバレッジ契約。 ページングされた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

読み取り専用、ペイロードは表示されず（ツール名/ステータス/行数のみ）、制限付き（小さな明示的なウィンドウ/ページ上限）— ここではテナントへの書き込みや1日を超えるログのスキャンは行われません。

リリース

このリポジトリはConventional Commitsによって駆動されるrelease-pleaseを使用しています。feat:/fix:のPRをmainにマージすると、release-pleaseがリリースPRを開く（または更新する）か、そのPRをマージするとリリースにタグ付けされ、公開パイプライン（PyPI、MCP Registry）がトリガーされます。

ライセンス

MIT