EntraID MCP サーバー (Microsoft Graph FastMCP)

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

特徴

• モジュラーリソース構造:

  • 各リソース (ユーザー、サインイン ログ、MFA など) はsrc/msgraph_mcp_server/resources/の下の独自のモジュールに実装されます。

  • 新しいリソース (グループ、デバイスなど) を簡単に拡張できます。

• 集中型グラフクライアント:

  • 認証とクライアントの初期化を処理します。

  • すべてのリソース モジュールで共有されます。

• 包括的なユーザー操作:

  • 名前/メールでユーザーを検索します。

  • ID でユーザーを取得します。

  • すべての特権ユーザー (ディレクトリ ロール メンバー) を一覧表示します。

• 完全なグループライフサイクルとメンバーシップ管理:

  • グループを作成、読み取り、更新、削除します。

  • グループのメンバーと所有者を追加/削除します。

  • グループとグループ メンバーを検索して一覧表示します。

• アプリケーションとサービスプリンシパルの管理:

  • アプリケーション (アプリ登録) を一覧表示、作成、更新、削除します。

  • サービス プリンシパルを一覧表示、作成、更新、および削除します。

  • アプリケーションとサービス プリンシパルの両方に対するアプリ ロールの割り当てと委任されたアクセス許可を表示します。

• サインインログ操作:

  • 過去 X 日間のユーザーのサインイン ログを照会します。

• MFA 操作:

  • ユーザーの MFA ステータスを取得します。

  • グループのすべてのメンバーの MFA ステータスを取得します。

• パスワード管理:

  • カスタムまたは自動生成された安全なパスワードを使用して、ユーザーのパスワードを直接リセットします。

  • 次回のサインイン時にパスワードの変更を要求するオプション。

• 権限ヘルパー:

  • 一般的なタスクに適切な Microsoft Graph 権限を提案します。

  • 利用可能なグラフ権限を検索して調べます。

  • 必要な権限のみを推奨することで、最小権限の原則を実装するのに役立ちます。

• エラー処理とログ記録:

  • FastMCP コンテキストを介した一貫したエラー処理と進行状況レポート。

  • トラブルシューティングのための詳細なログ記録。

• 安全：

  • .envおよび secret ファイルはバージョン管理から除外されます。

  • 認証には Microsoft のベスト プラクティスを使用します。

Related MCP server: ms-365-admin-mcp-server

プロジェクト構造

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インスペクターを備えたインタラクティブな開発環境が起動します。詳細情報と高度な使用方法については、 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 （オプション、「非公開」または「公開」）

  • owners （オプション、ユーザーIDのリスト）

  • members （オプション、IDのリスト）

  • membershipRule (動的グループの場合は必須)

  • membershipRuleProcessingState (オプション、「オン」または「一時停止」)

サポートされているフィールドと動作の詳細については、 groups.pyドキュメント文字列を参照してください。

サインインログツール

• 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やその他の機密ファイルは gitignored されます。

• 最小限の権限を使用する: Azure AD アプリに必要な Microsoft Graph 権限のみを付与します。

• **監査と監視:**トラブルシューティングと監視にログ出力を使用します。

必要なグラフAPI権限

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

上級：ClaudeまたはCursorと併用する

クロード（アントロピック）と併用

このサーバーを 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/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/と環境変数を実際の値に置き換えます。

• 本当の秘密をリポジトリにコミットしないでください。

ライセンス

マサチューセッツ工科大学