entraadm-mcp

English | 日本語

用于 Microsoft Entra ID 登录和审计日志分类的 MCP 服务器。只读。

为什么用这个而不是官方的 Microsoft MCP Server for Enterprise

微软发布了一个用于 Entra ID 数据的官方 MCP Server for Enterprise。它非常适合在键盘前进行交互式操作的管理员，但不适合无人值守的分类机器人：

• 仅支持委托身份验证。 官方服务器不支持仅应用（客户端凭据）身份验证，因此无法在服务账户后无头运行。entraadm-mcp 正是为此场景而构建：生产环境使用仅应用模式，本地开发则回退到委托（az login）模式。

• 通用 Graph 查询工具，而非固定工具集。 官方服务器只暴露一个工具，让模型可以对 Microsoft Graph 构造任意的 GET/schema 发现调用。这对人类来说很灵活，但放在自动化分类配置文件的允许列表后面就很别扭。entraadm-mcp 取而代之暴露了七个固定的只读工具。

• 没有 AADSTS 翻译。 登录失败以原始错误码返回；分类仍然需要查找表。entraadm-mcp 为每次登录失败标注该错误码的实际含义。

• 没有跨请求聚合。 Microsoft Graph 本身无法在服务端按 status/errorCode 过滤登录，也没有内置的密码喷洒视图。signin_failure_stats 在客户端聚合，并标记对许多不同用户有失败登录的 IP——这是 Entra 的按账户智能锁定本身无法捕获的模式。

Related MCP server: Microsoft Graph MCP Server

工具

每个工具都是只读的。写操作（解除账户阻止、重置密码、撤销会话）不在本服务器的范围内。

身份验证模型

两种身份验证模式，由设置了哪些环境变量来决定：

仅设置三个仅应用变量中的一两个属于配置错误，服务器会拒绝启动，而不是静默回退到与预期不同的身份验证模式。

所需的 Graph 权限

缺少权限绝不会导致工具崩溃。它只会将该工具（或该字段）降级为 {"error": "...", "missing_permission": "..."}，并附上需要什么角色或权限的人类可读说明，因此即使在授予完整权限之前，health_check 和所有其他工具也保持可用。

设置

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

配置

为生产/无人值守使用设置三个仅应用变量：

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

或者全部不设置，先运行 az login 进行本地开发。

可选：

# Default page cap for the log-scanning tools (1-50, default 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

用法

Claude Code（插件）

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code（手动）

添加到 .mcp.json：

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

直接执行

entraadm-mcp

CLI 选项

备注

• 覆盖契约。 每个遍历分页 Graph 集合的结果，在其时间窗口未被完全扫描时都会携带 capped 布尔值——部分扫描绝不会被报告为穷尽扫描。

• found: false 不是错误。 get_user 和 get_user_auth_methods 对不存在的账户返回 {"found": false, ...}，而不是 error 键——拼错的 userPrincipalName 绝不应看起来像是本服务器出了问题。

• 保留期。 Entra ID P1 将登录和目录审计日志保留 30 天。超出该范围的时间窗口返回空结果，而不是错误。

开发

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

实时冒烟测试

uv run python scripts/smoke_test.py

只读，不打印负载（仅工具名称/状态/行数），且有界（明确的小时间窗口/页数上限）——这里没有任何操作会写入租户或扫描超过一天的日志。

发布

本仓库使用由 Conventional Commits 驱动的 release-please。将 feat:/fix: PR 合并到 main，release-please 会打开（或更新）一个发布 PR；合并该 PR 会标记一个发布版本并触发发布流水线（PyPI、MCP Registry）。

许可证

MIT