MSGraph MCP

MSGraph MCP

一个用于 Microsoft Graph 的 Model Context Protocol（MCP）服务。它通过 Microsoft Graph SDK 向 AI Agent 提供 Microsoft Outlook 邮件和日历，以及只读的 Microsoft Teams 消息历史记录。它以已登录用户的身份运行，使用委托权限和 MSAL 设备代码流，因此只能访问该用户可访问的内容。

安装

你需要 Python ≥ 3.11 和一个 Entra（Azure AD）应用注册。应用注册大约需要 10 分钟，且可能需要管理员协助，因此请先完成此步骤：参见下方的 Entra 设置部分。

uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server

该软件包名为 msgraph-mcp-server。它会安装三个命令：msgraph-mcp 及其别名 msgraph-mcp-server，两者都会启动 stdio 服务；另外还有用于一次性登录的 msgraph-mcp-login。

设置

1. 设置 Entra 应用凭据。

export MSGRAPH_MCP_CLIENT_ID=<your app's client ID>
export MSGRAPH_MCP_TENANT_ID=<your tenant ID>   # or: common / organizations / consumers

2. 登录一次。 此命令会显示一个 URL 和一段代码；访问该 URL 并输入代码。此过程不会使用或存储客户端密钥。

msgraph-mcp-login
# running via uvx instead of installing: uvx --from msgraph-mcp-server msgraph-mcp-login

令牌缓存会写入 ~/.msgraph-mcp/token_cache.bin。

3. 将服务接入 MCP 宿主。

Claude Code：

claude mcp add msgraph \
  --env MSGRAPH_MCP_CLIENT_ID=$MSGRAPH_MCP_CLIENT_ID \
  --env MSGRAPH_MCP_TENANT_ID=$MSGRAPH_MCP_TENANT_ID \
  -- msgraph-mcp

其他任何通过 stdio 接入的宿主：

{
  "mcpServers": {
    "msgraph": {
      "command": "msgraph-mcp",
      "args": [],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<your app's client ID>",
        "MSGRAPH_MCP_TENANT_ID": "<your tenant ID>"
      }
    }
  }
}

若要在不安装的情况下运行，请使用 "command": "uvx" 和 "args": ["msgraph-mcp-server"]。请注意，uvx 不会将 msgraph-mcp-login 添加到你的 PATH，因此请使用第 2 步中所示的 uvx --from 形式登录。

MSGRAPH_MCP_TOKEN_CACHE_PATH 可用于覆盖缓存位置。三个变量也都可以从工作目录中的 .env 文件读取；进程环境变量的优先级高于该文件。

Entra 设置

应用注册需要：

• 账户类型： 单租户（多租户也可；将 MSGRAPH_MCP_TENANT_ID 设为 common、organizations 或 consumers）
• 重定向 URI（公共客户端）： https://login.microsoftonline.com/common/oauth2/nativeclient
• 允许公共客户端流： 是，在“Authentication → Advanced settings”下。若未启用，设备代码流会失败。
• 委托权限（Microsoft Graph）：
  • 邮件：Mail.ReadWrite、Mail.ReadWrite.Shared、Mail.Send
  • 规则：MailboxSettings.ReadWrite（Graph 的 messageRules 端点需要此权限）
  • 日历：Calendars.ReadWrite、Calendars.ReadWrite.Shared
  • 身份：User.Read
  • Teams：Chat.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Read.All

ChannelMessage.Read.All 始终需要租户管理员同意，*.Shared 权限则可能因租户而异，也需要管理员同意。

权限范围列表必须全部启用或全部不启用。 登录时会一次性请求所有权限范围，因此，如果 ChannelMessage.Read.All 未获得管理员同意，登录会直接失败，邮件和日历也无法使用。出于同样的原因，之后添加权限范围意味着必须重新运行 msgraph-mcp-login；在此之前，所有工具都会失败并报 NotAuthenticatedError，而不仅仅是需要新权限范围的工具。

工具

分组	工具
实用工具	whoami
邮件 — 读取	list_messages、search_messages、get_message、list_attachments、download_attachment
邮件 — 写入	send_message、create_draft、reply_message、reply_all_message、forward_message、update_message、delete_message
邮件 — 文件夹	list_folders、create_folder、update_folder、delete_folder、move_message
邮件 — 操作	archive_message、mark_read、mark_unread、flag_message、unflag_message
邮件 — 批量	batch_archive_messages、batch_move_messages、batch_mark_read、batch_mark_unread、batch_flag_messages、batch_unflag_messages
邮件 — 规则	list_rules、get_rule、create_rule、update_rule、delete_rule
日历	list_calendars、list_events、get_event、create_event、update_event、delete_event、cancel_event、respond_to_event、find_meeting_times
Teams（读取）	list_chats、list_chat_messages、list_joined_teams、list_channels、list_channel_messages、list_message_replies、download_hosted_content

各工具共用的行为：

• 精简响应。 结果会重新整理以便 Agent 使用，邮件和事件正文会替换为简短的 snippet。在 get_message、list_chat_messages、list_channel_messages 或 list_message_replies 中传入 include_body=true 可获取完整正文；对于 Teams，这也会显示 Adaptive Card 内容。在任何返回 Graph 对象的工具中传入 include_raw=true，即可在精简结果旁获取完整负载；batch_* 工具仅返回每封邮件的状态，不接受此参数。
• 其他邮箱。 每个邮件和日历工具都接受可选的 mailbox（电子邮件地址或用户 ID），用于指定共享邮箱或委派邮箱。若使用自己的邮箱，请省略此参数。Teams 工具为只读，仅涵盖你自己的聊天，且不接受 mailbox。
• 分页。 列表和搜索工具接受 limit（1-100，默认值为 25）和 page_token，但 list_channel_messages 和 list_message_replies 除外，Graph 对它们的上限为 50。list_folders、list_rules、list_attachments 和 list_calendars 会返回整个集合，且不接受这两个参数。对于 list_joined_teams 和 list_channels，由于 Graph 会拒绝 $top，limit 会在获取结果后应用，因此它能节省令牌，而非减少往返请求。
• 批量操作。 batch_* 工具通过 Graph 的 $batch 端点，对最多 1000 封邮件执行一项操作，并返回每封邮件的结果以及 {total, succeeded, failed} 汇总信息。
• 下载。 download_attachment 和 download_hosted_content 会将图片作为原生 MCP 图片块返回，供 Agent 查看。传入 save_path（文件路径或已存在的目录）可将字节写入磁盘，并改为返回路径。
• 查找邮件。 list_messages 默认搜索收件箱；传入 folder_id 可指定其他文件夹，传入 unread_only=true 可只查看未读邮件，也可传入原始 OData filter，以指定 KQL 无法表达的条件。search_messages 会将查询作为 KQL 传递给 Graph 的 $search。

每封邮件的外发附件总大小上限为 3 MB；不支持分块上传。SharePoint 支持的 Teams 文件附件无法下载，仅可下载内联托管内容。

安全

令牌缓存中保存着你的刷新令牌，它可以为你的邮件、日历和 Teams 数据生成访问令牌。请将该文件视为凭据。它位于 ~/.msgraph-mcp/token_cache.bin，文件权限为 0600，所在目录权限为 0700。

若要撤销访问权限或切换账户，请删除缓存并重新登录：

rm -f ~/.msgraph-mcp/token_cache.bin ~/.outlook-mcp/token_cache.bin

如果你曾以旧名称 outlook-mcp 运行此服务，第二个路径就很重要：当前缓存不存在时仍会将该缓存用作备用，因此只删除第一个文件会让有效的刷新令牌继续留在磁盘上。若要彻底撤销访问权限，还要在 https://account.microsoft.com 或组织的身份门户中移除此应用。

故障排除

• NotAuthenticatedError: Not authenticated — 运行 msgraph-mcp-login。如果问题立即再次出现，说明尚未同意某个请求的权限范围；请参阅 Entra 设置部分的说明。
• ConfigError: Missing required env var — 在 shell、工作目录中的 .env 文件或 MCP 主机的环境变量配置中设置该变量。
• Graph API 403: ErrorAccessDenied — Entra 应用缺少委托权限，或需要管理员同意。请查看上方列表，然后重新同意并登录。
• search_messages 返回 Graph API 400: BadRequest — Syntax error — 查询会以 KQL 格式传递给 Graph 的 $search。请为字面短语加引号（"weekly report"），或使用字段形式（from:alice）。对于 KQL 无法表达的谓词，请使用带有 filter= 的 list_messages。
• 主机启动了服务，但未列出任何工具 — 确认主机通过 stdio 启动 msgraph-mcp（或 uvx），且能在其 PATH 中找到该二进制文件。

开发

请参阅 CONTRIBUTING.md。