Microsoft 365 Mail

@mindstone/mcp-server-microsoft-mail

Microsoft 365 Outlook 邮件 MCP 服务——通过 Microsoft Graph API 列出、搜索、读取、发送、回复、转发、草拟、移动和删除邮件，下载附件、读取邮件对话串、整理邮件（标记已读／加旗标），以及管理外出自动回复。

面向群组协作的 Microsoft 365 邮件 MCP。由宿主负责 OAuth 流程，本服务从磁盘读取各账户的令牌；每个工具都会通过结构化的 auth_required 封装在认证失败时拒绝操作，以便宿主引导用户重新认证。

状态

• 版本： 0.3.0 · npm
• 认证： OAuth（由宿主协调）(MS_CLIENT_ID)
• 工具： 22（邮件、文件夹、草稿、附件、邮件对话串、设置）
• 接口类型： cloud-api
• 机器可读： STATUS.json
• 共享库： @mindstone/mcp-server-microsoft-shared

为什么开发此项目

我们在 2026 年 5 月移植此项目时，Microsoft 自家的 Graph MCP 系列尚未推出独立的 Outlook 邮件服务，当时的社区方案在 OAuth 期间都会自行运行浏览器回调服务；而我们的宿主应用已经会为整个群组协作组完成此流程，并已协商好所需凭据。我们将 MindstoneRebel 中捆绑的连接器单独提取出来，并按原样移植，使同一组 Microsoft 365 五个连接器（邮件、日历、文件、Teams、SharePoint）共用一个 OAuth 接口，以及一个用于令牌持久化、请求超时和结构化 auth_required 封装的共享库包，宿主已能处理该封装并恢复操作。此连接器负责群组协作组的认证工具（authenticate_microsoft_account）；其他四个连接器则复用它所协商的凭据。

交互示例

“列出 Alice 发来的最近 5 封未读邮件，并回复最新的一封：‘谢谢，今晚会读。’”

宿主调用的工具：

1. search_emails — from:[email protected] isRead:false，最多返回 5 封。
2. reply_to_email — 使用结果列表中第一封邮件的 ID 发送回复，并附上提供的正文。

响应（删节）：

{
  "matches": [
    {
      "id": "AAMkAD...",
      "subject": "Q3 planning",
      "from": "[email protected]",
      "receivedDateTime": "2026-05-19T09:14:11Z"
    }
  ],
  "reply": {
    "id": "AAMkAD...",
    "isDraft": false
  }
}

要求

• Node.js 20+
• npm
• 一个负责执行 Microsoft OAuth 流程，并将各账户令牌文件写入 ${MS_CONFIG_DIR}/credentials/${sanitised-email}.token.json、同时维护 ${MS_CONFIG_DIR}/accounts.json 索引的宿主应用。本服务读取这些文件；不会自行发起 OAuth。

一键安装

点击按钮后，宿主将提示你填写：MS_CLIENT_ID、MS_CONFIG_DIR、MS_MCP_PACKAGE_ID、MICROSOFT_REQUEST_TIMEOUT_MS。

{
  "mcpServers": {
    "Microsoft 365 Mail": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-microsoft-mail"
      ],
      "env": {
        "MS_CLIENT_ID": "",
        "MS_CONFIG_DIR": "",
        "MS_MCP_PACKAGE_ID": "Microsoft365Mail",
        "MICROSOFT_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

快速入门

安装与构建

cd <path-to-repo>/connectors/microsoft-mail
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-microsoft-mail

本地

node dist/index.js

配置

此服务与负责 Microsoft 365 OAuth 流程的宿主应用一起运行。宿主会将凭据写入磁盘；此服务会读取这些凭据。

必需的环境变量

可选环境变量

宿主配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Microsoft365Mail": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-microsoft-mail"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

在宿主写入 ${MS_CONFIG_DIR}/credentials/<account>.token.json 和 ${MS_CONFIG_DIR}/accounts.json 之前，每次工具调用都会返回结构化的 auth_required 响应（宿主的 MCP 服务会识别此格式，并分发给已注册的 Microsoft 365 OAuth 协调器）。

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "Microsoft365Mail": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/microsoft-mail/dist/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

工具（22）

Graph 权限

邮件工具通过委托授权 Mail.ReadWrite + Mail.Send 运行。自动回复工具还需要 MailboxSettings.Read / MailboxSettings.ReadWrite；在许多组织中，这项权限必须由管理员批准。如果连接的账户缺少该权限，工具会返回指导信息封装，而不是原始的 Graph 403 错误。

排序和验证说明

• 筛选列表仅在当前页面内排序。 Microsoft Graph 不允许 $filter 与 $orderby 一起使用，因此当调用 list_emails 时指定了 filter（以及每次调用 get_conversation 时），连接器只会在客户端对返回的页面排序：Graph 会先应用 $top，因此结果是 Graph 返回页面的排序视图，而不是对整个邮箱进行全局排序扫描。未筛选的 list_emails 仍在服务器端排序。
• 收件人会经过验证。 to/cc/bcc 条目必须是电子邮件地址（会去除首尾空格，最多 254 个字符，每个字段最多 500 位收件人）；无效条目会在调用 Graph 前被拒绝。
• 计划的外出自动回复时间段必须使用 ISO 8601 日期时间；显式时区偏移量会转换为 UTC（不带时区的值按 UTC 处理），且开始时间必须早于结束时间。

安全说明

• 主机会以 0600 模式写入令牌文件；此服务通过 cohort-shared library 读取这些文件，该库遇到格式错误的文件时会默认拒绝操作。
• 云端环境默认设置 MICROSOFT_DISABLE_REFRESH=1，让桌面会话继续作为刷新令牌的唯一授权方，避免争用只能使用一次的刷新令牌。
• 成功的工具响应会移除仅 OSS 使用的 ok:true 包装，以匹配捆绑的 successResult 形状；手动验证或业务错误会返回 isError:true，并附带 { ok:false, error, action_required, next_step } 负载，以便主机的恢复层采取相应操作。
• 每个工具的 Graph 调用都会通过 .options({signal}) 和 Promise.race 包装器，在调用方与 cohort 组合的超时信号下运行，以增强防护。
• download_attachment 只会在 MCP_WORKSPACE_PATH 内（未设置时则在 OS 临时目录中）写入文件，会拒绝除普通文件名以外的任何名称，并将下载大小限制为 25 MB。附件字节流通过 $value 端点传输，并设有硬性字节上限（绝不会在超过上限后将内容完整载入内存）；元数据也以流方式传输，并设有硬性 1 MB 上限，原因相同；写入任何内容前，工作区根目录都会被规范化（解析符号链接）。每次下载都会保存到一个直接位于规范化工作区根目录下、以原子方式创建的全新私有暂存目录中（fs.mkdtemp，模式为 0700），并且只保留附件文件名；报告的 savedTo 指向该暂存目录内。由于目录名由连接器生成，因此不存在经验证的、用户可见的路径名可在验证与写入系统调用之间被预先植入、重命名或替换为符号链接；由此从根本上消除了父目录检查后使用的竞态条件，适用于所有平台，无需使用基于文件描述符的相对路径 API。文件本身通过独占打开方式创建（O_CREAT|O_EXCL，模式为 0600），因此不可能覆盖现有文件，也不会触碰同名的现有文件或符号链接；写入失败时会删除整个暂存目录，不留任何残留。攻击者控制的附件字段（名称、类型、内容类型）在任何以文本形式出现的位置都会用不可信内容封装，包括错误路径。savedTo 必须报告真实文件路径（主机需要该路径才能打开文件），但面向用户的 message 只会显示连接器生成的暂存目录名称，因此攻击者提供的文件名绝不会作为可信文本回显。
• 对于非身份验证失败，错误指引绝不会建议重新进行身份验证：遇到 Graph 403 权限拒绝时，连接器会提供本地指引，说明重新验证同一账户无济于事；上游 Graph 错误文本在传递给模型前会被封装为不可信内容。

许可证

FSL-1.1-MIT — Functional Source License 1.1 版，未来许可证为 MIT。允许用于非竞争性用途；在 LICENSE 中的转换日期后重新许可为 MIT。