用途
ms-graph-mcp 是一个 Model Context Protocol（MCP）服务器，用于让 AI 智能体访问 Microsoft Graph。它提供 85 个工具，覆盖 Outlook 邮件与日历、会议（包括转录）、Teams 聊天、文件、SharePoint、搜索、人员、联系人、目录、任务和 OneNote，可通过 stdio 或 Streamable HTTP 运行。
主要能力
- 工具覆盖：邮件、日历、会议（含转录）、Teams 聊天、文件、SharePoint、搜索、人员、联系人、目录、任务、OneNote。
- 认证方式：使用用户自己的 Microsoft 账户登录，浏览器 SSO，无需粘贴令牌，无需客户端密钥。
- 依赖精简：不使用 msgraph-sdk 和 azure-identity，Graph 客户端基于原始 httpx2，依赖树小且网络行为可检查。
- 读写分离：写工具默认隐藏并拒绝调用，除非调用方明确选择启用。
- 认证无关设计：默认情况下工具通过请求上下文接收已获取的 Graph 令牌；服务器也可执行自己的 on-behalf-of 交换，作为标准 OAuth 资源服务器运行。
- 工具集配置：通过 GRAPH_MCP_TOOLSETS 选择命名配置文件，每个配置文件是一组命名空间，可用逗号组合；默认 core，设置 all 可暴露全部工具。
- 工具命名：按 Graph 权限族而非 Microsoft 产品命名，因为实际问题常跨产品边界；例如 files_ 覆盖 OneDrive 和 SharePoint 文档库，底层是同一 driveItem 资源。
- 工具注解：每个工具声明 MCP 注解（readOnlyHint、destructiveHint、idempotentHint），每个描述说明所需的委托权限。
- 层级：内部层级不属于智能体表面，模型可见 76 个工具。按命名空间：mail 11、tasks 11、calendar 10、files 10、chat 8、directory 7、meetings 7、people 6、notes 5、search 1。
- 版本说明：0.2.0 中工具被重命名，所有 0.2.0 之前的工具名仍作为别名可用，并将持续到 0.4.0；别名在 tools/call 中有效，但不会在 tools/list 中公布。
使用方式
安装
要求 Python 3.12+。有两种路径：
A. 使用包：无需克隆，uv 可直接从 PyPI 运行，或安装到环境中。发布候选版本也会发布，pip 默认跳过，除非使用 --pre。HTTP 传输有 GHCR 容器镜像，见 docs/hosting.md。官方 MCP 注册表中列为 io.github.nitin27may/ms-graph-mcp。TestPyPI 不是分发渠道，仅用于发布演练，可能被清除且不镜像 PyPI，从它安装需要 --extra-index-url https://pypi.org/simple/ 才能解析普通依赖；建议使用 PyPI 或 --pre。
B. 从源码运行：适合修改、fork 或运行未发布变更。uv sync 是唯一设置步骤。打开 PR 前请阅读 CONTRIBUTING.md，工具允许列表和层级分离有强制不变量。要让 MCP 客户端指向克隆，需要其绝对路径，因为客户端不继承工作目录，且多数不展开 ~。
设置 Entra 应用
需要 Entra ID 应用注册，约两分钟。不要创建客户端密钥：注册为公共客户端，通过浏览器使用 PKCE 登录。在 Entra 门户 → 应用注册 → 新注册：名称任意，例如 ms-graph-mcp；支持的账户类型：仅此组织目录中的账户；重定向 URI：选择公共客户端/本机，值 http://localhost；证书和密钥留空。然后在新应用上：身份验证 → 启用允许公共客户端流；API 权限 → 添加权限 → Microsoft Graph → 委托权限，添加希望智能体访问的权限。合理的只读起始集：User.Read、Mail.Read、Calendars.Read、Files.Read.All、People.Read、Chat.Read、Tasks.Read、Notes.Read、Contacts.Read。完整的复制粘贴同意集以及每个工具所需的权限见 docs/permissions.md。从概述页复制应用程序（客户端）ID 和目录（租户）ID，这就是所需全部。
配置 MCP 客户端
每个支持 stdio 的 MCP 客户端都接受相同三样东西：命令、参数和环境块。首次登录会打开浏览器进行常规 Microsoft 365 SSO，包括 MFA 和条件访问。结果缓存在 ~/.ms-graph-mcp/token_cache.json，仅所有者可读，因此不会再次提示。
- VS Code：重新加载窗口，VS Code 会提示一次两个 ID 并记住，此文件可安全提交。打开聊天视图，切换到 Agent 模式，工具出现在工具选择器中。用 MCP: List Servers 确认。
- Claude Code：用 /mcp 确认，它会列出服务器及其工具。
- Claude Desktop：完全退出（不只是关闭窗口），重新打开，在编辑器中查找工具图标。
- Cursor 和 Windsurf：使用与 Claude Desktop 相同的 mcpServers 形状，放在上表所述文件中。
独立于任何客户端检查服务器的最快方式：需要 Node 22.19+，打开浏览器 UI，可列出工具并手动调用。也有可脚本化的 --cli 模式，见 docs/testing.md。用 -e 传递变量，而不是从 shell；Inspector 不会给其生成的服务器提供你的环境，因此 GRAPH_MCP_CLIENT_ID=… npx @modelcontextprotocol/inspector … 会以无客户端 ID 启动服务器；-e 标志放在服务器命令之后。
从源码运行时，使用与上述相同的块，将命令和参数替换为克隆的绝对路径。两个常见问题：uv 必须在客户端的 PATH 上，从 Finder 或 Dock 启动的 GUI 应用不继承 shell 的 PATH，如果发生这种情况，将 which uv 的输出放入 "command" 而不是裸名称；--directory 不是可选的，没有它，uv run 会针对客户端碰巧启动的目录解析，而不是项目。
配置
两个设置即可运行，其余都有可用默认值。每个设置、两种部署形态以及托管/OBO 选项见 docs/configuration.md。作为服务运行见 docs/hosting.md。
工具集配置文件
85 个工具对模型来说很多。GRAPH_MCP_TOOLSETS 选择命名配置文件，每个是一组命名空间，可用逗号组合。core 是默认值，因此除非要求，某些工具不会公布。如果需要 Teams 聊天、Planner、OneNote、会议转录或目录查找，请命名这些配置文件，或设置 GRAPH_MCP_TOOLSETS=all 暴露全部。通过 HTTP，调用方可发送 X-Toolsets 进一步收窄单个请求，只能收窄；启动值是上限，因此客户端请求 all 不会获得部署未启用的内容。这过滤可见性，而非权限；写范围和内部层级门才是实际阻止调用的机制。
适用场景
- 让 AI 智能体访问 Microsoft 365 数据：邮件、日历、会议转录、Teams 聊天、文件、SharePoint、OneNote、任务、目录、人员、联系人。
- 需要读写分离和明确权限控制的智能体集成。
- 需要 stdio 或 Streamable HTTP 传输的 MCP 客户端，如 VS Code、Claude Code、Claude Desktop、Cursor、Windsurf。
- 希望依赖精简、网络行为可检查的部署。
限制
- 状态：早期。从生产智能体平台提取，已在真实租户运行，代码经过实战检验，但打包和公共 API 表面较新，配置表面在 1.0 前可能变动。
- SharePoint 站点和列表是最大缺口；目录补全、文件移动/删除和邮件草稿随后。
- 主权云（GCC High / 21Vianet）目前不支持。完整列表和有意排除的范围见 docs/roadmap.md。
- 需要 Python 3.12+。
- 从源码运行时，uv 必须在客户端 PATH 上，且 --directory 不是可选的。
- 通过 HTTP 的 X-Toolsets 只能收窄，不能扩大启动时启用的范围。
- 内部层级不属于智能体表面，模型可见 76 个工具。
- 0.2.0 之前的工具名作为别名可用，但不会在 tools/list 中公布，将持续到 0.4.0。
- 文档：发布为可搜索站点 https://nitinksingh.com/ms-graph-mcp/。
- 支持：设置和应用注册问题 → Discussions；错误 → Issues，附终端运行服务器的输出；安全漏洞 → 绝不公开 issue，见 SECURITY.md。切勿将访问令牌、客户端密钥或共享密钥粘贴到任何地方。
- 许可证：MIT，见 LICENSE。
