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和密钥文件被排除在版本控制之外。
  • 使用微软的最佳实践进行身份验证。

项目结构

src/msgraph_mcp_server/
├── auth/ # 身份验证逻辑 (GraphAuthManager)
├── resources/ # 资源模块 (用户, 登录日志, MFA, ...)
│ ├── users.py # 用户操作 (搜索, 通过ID获取等)
│ ├── signin_logs.py # 登录日志操作
│ ├── mfa.py # MFA状态操作
│ ├── permissions_helper.py # Graph权限工具和建议
│ ├── applications.py # 应用程序 (应用注册) 操作
│ ├── service_principals.py # 服务主体操作
│ └── ... # 其他资源模块
├── utils/ # 核心GraphClient及其他实用工具, 如密码生成器...
├── server.py # FastMCP服务器入口点 (注册工具/资源)
├── init.py # 包标记

使用方法

1. 设置

• 克隆仓库。

• 创建一个包含Azure AD凭据的config/.env文件：

  TENANT_ID=你的租户ID
  CLIENT_ID=你的客户端ID
  CLIENT_SECRET=你的客户端密钥

• （可选）如果需要，设置基于证书的身份验证。

2. 测试与开发

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

bash
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) — 获取用户的登录日志

多因素身份验证工具

• get_user_mfa_status(user_id, ctx) — 获取用户的多因素身份验证状态
• get_group_mfa_status(group_id, ctx) — 获取组内所有成员的多因素身份验证状态

设备工具

• 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) — 获取过去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 权限

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

高级：与 Claude 或 Cursor 结合使用

与 Claude (Anthropic) 结合使用

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

bash
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 中（不要在版本控制中包含实际的密钥）：

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": "",
"CLIENT_ID": "",
"CLIENT_SECRET": ""
}
}
}

• 将 /path/to/ 和环境变量替换为您实际的值。
• 切勿将真实的密钥提交到您的仓库中！

许可证

MIT