EntraID MCP Server (Microsoft Graph FastMCP)

EntraID MCP 服务（Microsoft Graph FastMCP）

此项目提供了一个模块化、以资源为中心的 FastMCP 服务，用于与 Microsoft Graph API 交互。该服务旨在实现可扩展性、可维护性和安全性，并支持针对用户、登录日志、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. 设置

• 克隆代码库。
• 创建 config/.env 文件并填入 Azure AD 凭据：

  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 文档字符串。

登录日志工具

• 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 天内所有相关的目录审计日志

密码管理工具

• 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	Application	读取所有审计日志数据
AuthenticationContext.Read.All	Application	读取所有身份验证上下文信息
DeviceManagementManagedDevices.Read.All	Application	读取 Microsoft Intune 设备
Directory.Read.All	Application	读取目录数据
Group.Read.All	Application	读取所有组
GroupMember.Read.All	Application	读取所有组成员关系
Group.ReadWrite.All	Application	创建、更新和删除组；管理组成员和所有者
Policy.Read.All	Application	读取组织的策略
RoleManagement.Read.Directory	Application	读取所有目录 RBAC 设置
User.Read.All	Application	读取所有用户的完整个人资料
User-PasswordProfile.ReadWrite.All	Application	更新 passwordProfile 属性所需的最低权限
UserAuthenticationMethod.Read.All	Application	读取所有用户的身份验证方法
Application.ReadWrite.All	Application	创建、更新和删除应用程序（应用注册）及服务主体

注意： 创建、更新和删除组，以及添加或移除组成员或所有者，都需要 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