EntraID MCP Server (Microsoft Graph FastMCP)

EntraID MCP Server（Microsoft Graph FastMCP）

このプロジェクトは、Microsoft Graph API と連携するためのモジュール式のリソース指向 FastMCP サーバーを提供します。拡張性、保守性、セキュリティを重視して設計されており、ユーザー、サインインログ、MFA の状態、特権ユーザーに関する高度なクエリに対応しています。

機能

• モジュール式のリソース構成：
  • 各リソース（ユーザー、サインインログ、MFA など）は、src/msgraph_mcp_server/resources/ の下にある独自のモジュールで実装されています。
  • 新しいリソース（グループ、デバイスなど）を簡単に追加できます。
• 一元化された Graph クライアント：
  • 認証とクライアントの初期化を処理します。
  • すべてのリソースモジュールで共有されます。
• 包括的なユーザー操作：
  • 名前またはメールアドレスでユーザーを検索します。
  • ID でユーザーを取得します。
  • すべての特権ユーザー（ディレクトリロールのメンバー）を一覧表示します。
• グループのライフサイクル全般とメンバーシップ管理：
  • グループの作成、読み取り、更新、削除を行います。
  • グループメンバーと所有者を追加または削除します。
  • グループとグループメンバーを検索、一覧表示します。
• アプリケーションとサービスプリンシパルの管理：
  • アプリケーション（アプリの登録）を一覧表示、作成、更新、削除します。
  • サービスプリンシパルを一覧表示、作成、更新、削除します。
  • アプリケーションとサービスプリンシパルの両方について、アプリロールの割り当てと委任されたアクセス許可を確認できます。
• サインインログ操作：
  • 過去 X 日間のユーザーのサインインログをクエリします。
• MFA 操作：
  • ユーザーの MFA 状態を取得します。
  • グループのすべてのメンバーの MFA 状態を取得します。
• パスワード管理：
  • カスタムまたは自動生成された安全なパスワードを使って、ユーザーのパスワードを直接リセットします。
  • 次回サインイン時にパスワードの変更を要求するオプションがあります。
• アクセス許可ヘルパー：
  • 一般的なタスクに適した Microsoft Graph のアクセス許可を提案します。
  • 利用可能な Graph のアクセス許可を検索、確認できます。
  • 必要なアクセス許可のみを推奨することで、最小権限の原則の実践に役立ちます。
• エラー処理とログ記録：
  • FastMCP のコンテキストを通じて、一貫したエラー処理と進捗報告を行います。
  • トラブルシューティングに役立つ詳細なログを記録します。
• セキュリティ：
  • .env ファイルとシークレットファイルはバージョン管理から除外されています。
  • Microsoft の認証に関するベストプラクティスを採用しています。

プロジェクト構成

src/msgraph_mcp_server/
├── auth/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── mfa.py              # MFA status operations
│   ├── permissions_helper.py # Graph permissions utilities and suggestions
│   ├── applications.py       # Application (app registration) operations
│   ├── service_principals.py # Service principal operations
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

使用方法

1. セットアップ

• リポジトリをクローンします。
• Azure AD の認証情報を記載した config/.env ファイルを作成します。

  TENANT_ID=your-tenant-id
  CLIENT_ID=your-client-id
  CLIENT_SECRET=your-client-secret
  

• 必要に応じて、証明書ベースの認証を設定します（任意）。

2. テストと開発

FastMCP CLI を使って、MCP サーバーを直接テスト、開発できます。

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

これにより、MCP Inspector を備えた対話型の開発環境が起動します。詳しい情報と高度な使い方については、FastMCP のドキュメントを参照してください。

3. 利用可能なツール

ユーザーツール

• search_users(query, ctx, limit=10) — 名前またはメールアドレスでユーザーを検索します
• get_user_by_id(user_id, ctx) — ID でユーザーの詳細を取得します
• get_privileged_users(ctx) — 特権ディレクトリロールに属するすべてのユーザーを一覧表示します
• get_user_roles(user_id, ctx) — ユーザーに割り当てられたすべてのディレクトリロールを取得します
• get_user_groups(user_id, ctx) — ユーザーが所属するすべてのグループ（推移的なメンバーシップを含む）を取得します

グループツール

• get_all_groups(ctx, limit=100) — すべてのグループを取得します（ページング対応）
• get_group_by_id(group_id, ctx) — IDで特定のグループを取得します
• search_groups_by_name(name, ctx, limit=50) — 表示名でグループを検索します
• get_group_members(group_id, ctx, limit=100) — グループ IDでグループのメンバーを取得します
• create_group(ctx, group_data) — 新しいグループを作成します（group_data のフィールドについては以下を参照）
• update_group(group_id, ctx, group_data) — 既存のグループを更新します（フィールド：displayName、mailNickname、description、visibility）
• delete_group(group_id, ctx) — IDでグループを削除します
• add_group_member(group_id, member_id, ctx) — メンバー（ユーザー、グループ、デバイスなど）をグループに追加します
• remove_group_member(group_id, member_id, ctx) — グループからメンバーを削除します
• add_group_owner(group_id, owner_id, ctx) — グループに所有者を追加します
• remove_group_owner(group_id, owner_id, ctx) — グループから所有者を削除します

グループの作成／更新の例：

• create_group と update_group の group_data は、次のようなキーを持つ辞書にしてください：
  • displayName（作成時に必須）
  • mailNickname（作成時に必須）
  • description（任意）
  • groupTypes（任意。例：["Unified"]）
  • mailEnabled（任意）
  • securityEnabled（任意）
  • visibility（任意。「Private」または「Public」）
  • owners（任意。ユーザー ID のリスト）
  • members（任意。ID のリスト）
  • membershipRule（動的グループでは必須）
  • membershipRuleProcessingState（任意。「On」または「Paused」）

対応するフィールドと動作の詳細については、groups.py の docstring を参照してください。

サインインログツール

• get_user_sign_ins(user_id, ctx, days=7) — ユーザーのサインインログを取得します

MFA ツール

• get_user_mfa_status(user_id, ctx) — ユーザーの MFA 状態を取得します
• get_group_mfa_status(group_id, ctx) — グループメンバー全員の MFA 状態を取得します

デバイスツール

• get_all_managed_devices(filter_os=None) — すべての管理対象デバイスを取得します（必要に応じて OS で絞り込み）
• get_managed_devices_by_user(user_id) — 特定のユーザーのすべての管理対象デバイスを取得します

条件付きアクセス ポリシーツール

• get_conditional_access_policies(ctx) — すべての条件付きアクセスポリシーを取得します
• get_conditional_access_policy_by_id(policy_id, ctx) — IDで単一の条件付きアクセスポリシーを取得します

監査ログツール

• get_user_audit_logs(user_id, days=30) — 過去 N 日以内の、user_id に該当するユーザーのすべての関連するディレクトリ監査ログを取得します

パスワード管理ツール

• reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — 指定したパスワード値を使うか、安全なランダムパスワードを生成してユーザーのパスワードをリセットします

権限ヘルパーツール

• suggest_permissions_for_task(task_category, task_name) — 一般的なマッピングに基づき、特定のタスクに必要な Microsoft Graph 権限を提案します
• list_permission_categories_and_tasks() — 権限の提案で利用できるカテゴリとタスクをすべて一覧表示します
• get_all_graph_permissions() — Microsoft Graph API から Microsoft Graph のすべての権限を直接取得します
• search_permissions(search_term, permission_type=None) — キーワードで Microsoft Graph の権限を検索します

アプリケーションツール

• list_applications(ctx, limit=100) — テナント内のすべてのアプリケーション（アプリ登録）をページングしながら一覧表示します
• get_application_by_id(app_id, ctx) — オブジェクト ID を指定して特定のアプリケーションを取得します（アプリロールの割り当てと委任されたアクセス許可を含みます）
• create_application(ctx, app_data) — 新しいアプリケーションを作成します（app_data のフィールドについては以下を参照）
• update_application(app_id, ctx, app_data) — 既存のアプリケーションを更新します（フィールド：displayName、signInAudience、tags、identifierUris、web、api、requiredResourceAccess）
• delete_application(app_id, ctx) — オブジェクト ID を指定してアプリケーションを削除します

アプリケーションの作成／更新例：

• create_application と update_application の app_data は、次のようなキーを含む辞書にします：
  • displayName（作成時に必須）
  • signInAudience（任意）
  • tags（任意）
  • identifierUris（任意）
  • web（任意）
  • api（任意）
  • requiredResourceAccess（任意）

サービスプリンシパルツール

• list_service_principals(ctx, limit=100) — テナント内のすべてのサービスプリンシパルをページングしながら一覧表示します
• get_service_principal_by_id(sp_id, ctx) — オブジェクト ID を指定して特定のサービスプリンシパルを取得します（アプリロールの割り当てと委任されたアクセス許可を含みます）
• create_service_principal(ctx, sp_data) — 新しいサービスプリンシパルを作成します（sp_data のフィールドについては以下を参照）
• update_service_principal(sp_id, ctx, sp_data) — 既存のサービスプリンシパルを更新します（フィールド：displayName、accountEnabled、tags、appRoleAssignmentRequired）
• delete_service_principal(sp_id, ctx) — オブジェクト ID を指定してサービスプリンシパルを削除します

サービスプリンシパルの作成／更新例：

• create_service_principal と update_service_principal の sp_data は、次のようなキーを含む辞書にします：
  • appId（作成時に必須）
  • accountEnabled（任意）
  • tags（任意）
  • appRoleAssignmentRequired（任意）
  • displayName（任意）

リソースの例

• greeting://{name} — パーソナライズされた挨拶を返します

サーバーの拡張

• resources/ の下に新しいリソースモジュール（例：groups.py、devices.py）を追加します。
• FastMCP の @mcp.tool() デコレーターを使用して、server.py に新しいツールを登録します。
• すべての API 呼び出しには共有の GraphClient を使用します。

セキュリティとベストプラクティス

• シークレットをコミットしないでください： .env などの機密ファイルは gitignore で除外されています。
• 最小権限を使用してください： Azure AD アプリには、必要な Microsoft Graph のアクセス許可のみを付与します。
• 監査と監視を行ってください： トラブルシューティングと監視には、ログ出力を使用します。

必要な Graph API のアクセス許可

API / アクセス許可	種類	説明
AuditLog.Read.All	アプリケーション	すべての監査ログデータを読み取ります
AuthenticationContext.Read.All	アプリケーション	すべての認証コンテキスト情報を読み取ります
DeviceManagementManagedDevices.Read.All	アプリケーション	Microsoft Intune デバイスを読み取ります
Directory.Read.All	アプリケーション	ディレクトリデータを読み取ります
Group.Read.All	アプリケーション	すべてのグループを読み取ります
GroupMember.Read.All	アプリケーション	すべてのグループメンバーシップを読み取ります
Group.ReadWrite.All	アプリケーション	グループの作成、更新、削除、およびグループメンバーと所有者の管理
Policy.Read.All	アプリケーション	組織のポリシーを読み取ります
RoleManagement.Read.Directory	アプリケーション	すべてのディレクトリ RBAC 設定を読み取ります
User.Read.All	アプリケーション	すべてのユーザーの完全なプロフィールを読み取ります
User-PasswordProfile.ReadWrite.All	アプリケーション	passwordProfile プロパティを更新するために必要な最小権限
UserAuthenticationMethod.Read.All	アプリケーション	すべてのユーザーの認証方法を読み取ります
Application.ReadWrite.All	アプリケーション	アプリケーション（アプリの登録）とサービスプリンシパルを作成、更新、削除します

注： グループの作成、更新、削除、およびグループメンバーや所有者の追加・削除には、Group.ReadWrite.All が必要です。読み取り専用のグループおよびメンバーシップのクエリには、Group.Read.All と GroupMember.Read.All で十分です。

応用：Claude または Cursor での使用

Claude（Anthropic）での使用

このサーバーを Claude MCP ツールとしてインストールして実行するには、次のコマンドを使用します。

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
  -f /path/to/.env

• /path/to/ を実際のプロジェクトパスに置き換えます。
• -f フラグは .env ファイルを指定します（シークレットは絶対にコミットしないでください！）。

Cursor での使用

次の内容を .cursor/mcp.json に追加します（バージョン管理に実際のシークレットを含めないでください）。

{
  "EntraID MCP Server": {
    "command": "uv",
    "args": [
      "run",
      "--with", "azure-core",
      "--with", "azure-identity",
      "--with", "fastmcp",
      "--with", "msgraph-core",
      "--with", "msgraph-sdk",
      "fastmcp",
      "run",
      "/path/to/src/msgraph_mcp_server/server.py"
    ],
    "env": {
      "TENANT_ID": "<your-tenant-id>",
      "CLIENT_ID": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}

• /path/to/ と環境変数を実際の値に置き換えます。
• 実際のシークレットをリポジトリに絶対にコミットしないでください！

ライセンス

MIT