Azure Entra MCP

微软Entra MCP服务器

FastMCP服务器，为AI助手提供对Microsoft Entra（Azure AD）目录服务的访问。此服务器使LLM能够使用Microsoft Graph API搜索用户、组和检查成员身份。

特性

• 🔍 4工具：搜索用户、搜索组、获取用户成员资格、获取组成员
• 🧠 全文搜索：使用Microsoft Graph $search 使用AND标记化进行顺序无关的匹配（例如，“Arun AND Singh”匹配“Singh，Arun”和“Arun Kumar Singh”）
• 📈 准确计数：用途 ConsistencyLevel: eventual 随着 $count=true 分页 @odata.nextLink
• 🔁 分页：对用户、组和组成员进行分页，以返回不超过限制的完整结果
• 🆔 强健的标识符解析：成员查找在查询之前从电子邮件/UPN解析用户ID
• 🎨 7提示：用于常见Entra查询的预构建提示模板
• 🔐 安全认证：使用客户端凭据注册Azure AD应用程序
• 🌐 健康端点：用于监测的内置健康检查
• ✅ 经过全面测试：带pytest的全面测试套件

先决条件

Azure AD应用程序注册

1. 转到Azure门户→ 微软Entra ID→ 应用程序注册
2. 创建新的应用程序注册
3. 记下：

- 应用程序（客户端）ID - 目录（租户）ID

1. 在证书和机密下创建客户端机密
2. 授予以下Microsoft Graph API权限：

- User.Read.All - Group.Read.All - GroupMember.Read.All

环境变量

在运行之前设置这些环境变量。您可以：

选项1：直接环境变量

export ENTRA_TENANT_ID="your-tenant-id-here"
export ENTRA_CLIENT_ID="your-client-id-here"
export ENTRA_CLIENT_SECRET="your-client-secret-here"

选项2：使用.env文件

cp env.template .env
# Edit .env with your actual values

服务器将自动从 .env 文件（如果存在）。

快速开始

安装

pip install -r requirements.txt

本地运行

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export ENTRA_TENANT_ID="..."
export ENTRA_CLIENT_ID="..."
export ENTRA_CLIENT_SECRET="..."

# Run the server
python main.py

服务器将于启动 http://0.0.0.0:8001

使用Docker

# Build the image
docker build -t entra-mcp .

# Run the container with environment variables
docker run -p 8001:8001 \
  -e ENTRA_TENANT_ID="..." \
  -e ENTRA_CLIENT_ID="..." \
  -e ENTRA_CLIENT_SECRET="..." \
  entra-mcp

API 参考

工具

1. search_entra_users

按显示名称、电子邮件或用户主体名称搜索用户。

参数：

搜索行为：

• 全文横跨 displayName, mail，以及 userPrincipalName 使用Graph $search
• 为了获得更好的相关性，令牌会进行AND处理（例如，“Arun Singh”→ "Arun" AND "Singh")，匹配与顺序无关的名称和中间名
• 用途 ConsistencyLevel: eventual 和 $count=true 为了获得准确的总计
• 分页跨越 @odata.nextLink 并返回到 max_results

示例用法：

# Order-agnostic and middle-name tolerant
search_entra_users(query="Arun Singh", max_results=25)

# Also matches comma-separated and compound names
search_entra_users(query="Singh, Arun", max_results=25)

# Email or UPN fragments are also matched by `$search`
search_entra_users(query="arun.singh@company.com")

2. search_entra_groups

按显示名称或描述搜索组。

参数：

搜索行为：

• 全文横跨 displayName 和 description 使用Graph $search 和and标记化术语
• 用途 ConsistencyLevel: eventual 和 $count=true 为了获得准确的总计
• 分页跨越 @odata.nextLink 并返回到 max_results

3. get_user_group_membership

获取用户所属的所有组。

参数：

行为：

• 需要时自动从电子邮件/UPN解析用户ID
• 用途 ConsistencyLevel: eventual, $count=true，并分页 @odata.nextLink

4. get_group_members

获取组中的所有成员。

参数：

行为：

• 用途 ConsistencyLevel: eventual 并分页 @odata.nextLink
• 返回高达 max_results 成员

可用提示

1. find_user_by_name

按显示名称查找用户。

默认值现在建议更广泛的搜索和更高的限制来利用 $search:

# Suggests: Call search_entra_users with: query='{name}', max_results=25

2. find_user_by_email

通过电子邮件地址查找用户。

3. find_group_by_name

按名称查找组。

4. check_user_groups

检查用户属于哪些组。

5. list_group_members

列出特定组的所有成员。

6. user_access_audit

对用户执行访问审核。

7. group_membership_audit

审核安全敏感组的成员资格。

测试

健康检查

curl http://localhost:8001/health

运行测试套件

# Run all tests
python -m pytest tests/ -v

项目结构

streamable-HTTP-Entra-MCP/
├── main.py              # Main server with tools and authentication
├── promptz.py           # Prompt templates for LLMs (7 prompts)
├── requirements.txt     # Python dependencies
├── README.md           # This file
└── tests/
    ├── __init__.py
    └── test_main.py    # Tests for main functionality

安全说明

• 服务器需要Azure AD应用程序权限才能读取用户和组数据
• 所有API调用都使用客户端凭据流进行身份验证
• 没有用户数据存储在本地-所有查询都直接进入Microsoft Graph API
• 确保您的Azure AD应用程序具有所需的最低权限

使用的图形查询语义

• ConsistencyLevel: eventual 是必需的 $search 和 $count
• $search 对值进行AND标记，以提高相关性并处理名称顺序变化
• $count=true 要求返回准确的总计
• 结果通过以下方式分页 @odata.nextLink 直到达到极限

用例

• 🔍 用户查找：通过姓名或电子邮件查找用户信息
• 👥 群组发现：搜索可用组
• 🔐 访问控制：检查用户组成员的权限
• 📊 审计与合规：查看组成员资格和用户访问权限
• 🤖 AI助理：使LLM能够回答有关Entra目录的问题

依赖项

核心：

• fastmcp==2.13.0.1 -MCP服务器的FastMCP框架
• httpx==0.28.1 -异步HTTP客户端
• azure-identity==1.19.0 -Azure身份验证
• msal==1.31.0 -Microsoft身份验证库

发展：

• pytest==8.3.4 -测试框架
• pytest-asyncio==0.24.0 -异步测试支持

API数据源

此服务器使用Microsoft Graph API：

• 基本URL: https://graph.microsoft.com/v1.0
• 认证：客户端凭据流
• 范围: https://graph.microsoft.com/.default

故障排除

身份验证错误

# Check environment variables are set
echo $ENTRA_TENANT_ID $ENTRA_CLIENT_ID $ENTRA_CLIENT_SECRET

# Verify Azure AD app permissions in Azure Portal
# Ensure client secret is not expired

导入错误

# Install dependencies
pip install -r requirements.txt

# Verify Azure packages
pip list | grep azure

许可证

看 许可证 文件以获取详细信息。

______________________________________________________________________

内置❤️ 使用FastMCP和Microsoft Graph API