EntraID MCP Server

EntraID MCP 服务器（Microsoft Graph FastMCP）

该项目提供了一个模块化、面向资源的 FastMCP 服务器，用于与 Microsoft Graph API 交互。它注重可扩展性、可维护性和安全性，支持针对用户、登录日志、MFA 状态和特权用户的高级查询。

特征

• 模块化资源结构：
  • 每个资源（用户、登录日志、MFA 等）都在src/msgraph_mcp_server/resources/下的自己的模块中实现。
  • 易于扩展新资源（例如，群组、设备）。
• 集中式图形客户端：
  • 处理身份验证和客户端初始化。
  • 所有资源模块共享。
• 全面的用户操作：
  • 按姓名/电子邮件搜索用户。
  • 通过 ID 获取用户。
  • 列出所有特权用户（目录角色成员）。
• 完整的群组生命周期和会员管理：
  • 创建、读取、更新和删除组。
  • 添加/删除组成员和所有者。
  • 搜索并列出群组和群组成员。
• 应用程序和服务主体管理：
  • 列出、创建、更新和删除应用程序（应用程序注册）。
  • 列出、创建、更新和删除服务主体。
  • 查看应用程序和服务主体的应用角色分配和委派权限。
• 登录日志操作：
  • 查询用户最近X天的登录日志。
• MFA 操作：
  • 获取用户的 MFA 状态。
  • 获取群组所有成员的 MFA 状态。
• 密码管理：
  • 使用自定义或自动生成的安全密码直接重置用户密码。
  • 下次登录时要求更改密码的选项。
• 权限助手：
  • 针对常见任务建议适当的 Microsoft Graph 权限。
  • 搜索并探索可用的 Graph 权限。
  • 通过仅推荐必要的权限来帮助实现最小特权原则。
• 错误处理和日志记录：
  • 通过 FastMCP 上下文进行一致的错误处理和进度报告。
  • 用于故障排除的详细日志记录。
• 安全：
  • .env和 secret 文件被排除在版本控制之外。
  • 使用 Microsoft 最佳实践进行身份验证。

项目结构

用法

1. 设置

• 克隆 repo。
• 使用您的 Azure AD 凭据创建一个config/.env文件：
  TENANT_ID=your-tenant-id CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret
• （可选）如果需要，设置基于证书的身份验证。

2.测试与开发

您可以使用 FastMCP CLI 直接测试和开发您的 MCP 服务器：

这将启动一个带有 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) — 获取所有托管设备（可选择按操作系统过滤）
• 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) — 根据 user_id 获取过去 N 天内用户的所有相关目录审计日志

密码管理工具

• 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 权限。
• **审计和监控：**使用日志输出进行故障排除和监控。

所需的 Graph API 权限

**注意：**创建、更新、删除群组以及添加/移除群组成员或所有者都需要Group.ReadWrite.All权限。对于只读群组和成员资格查询， Group.Read.All和GroupMember.Read.All权限已足够。

高级：与 Claude 或 Cursor 一起使用

与 Claude (Anthropic) 一起使用

要安装并运行此服务器作为 Claude MCP 工具，请使用：

• 将/path/to/替换为您的实际项目路径。
• -f标志指向您的.env文件（永不提交秘密！）。

与游标一起使用

将以下内容添加到您的.cursor/mcp.json （不要在版本控制中包含实际机密）：

• 将/path/to/和环境变量替换为您的实际值。
• 永远不要将真正的秘密提交到您的存储库！

执照

麻省理工学院