Outlook Mail

一个模型上下文协议服务，可让 Claude、Codex 及其他任何 MCP 客户端通过 Microsoft Graph API 读取、搜索、发送和整理你的 Outlook / Microsoft 365 / Outlook.com 邮件。

---

🔭 概览

outlook-mcp 在本地通过 stdio 运行。它使用 OAuth 设备代码流登录（无需客户端密钥或重定向 URI），将刷新令牌存储在你的操作系统密钥链中（或仅你本人可读取的本地文件中），并通过普通的 fetch 与 Microsoft Graph 通信。

✨ 功能

• 📂 浏览文件夹、列出和搜索邮件（KQL），并以经过清理的纯文本形式读取正文
• 📎 安全地列出附件并将其下载到配置的目录
• ✉️ 发送邮件、创建草稿、回复、回复所有人和转发（本地附件最大 150 MB；3 MB 或更大的文件会分块上传）
• 🗂️ 移动、标记为已读/未读、加旗标和删除邮件，可逐封操作或批量操作（ids）
• 📰 查找新闻简报、取消订阅，并通过收件箱规则阻止不需要的发件人
• 🔒 只读模式，可移除所有修改类工具
• 🔁 遇到限流时（429/503/504），根据 Retry-After / 指数退避自动重试
• 🧾 日志仅写入 stderr；绝不记录令牌或邮件正文

📋 要求

• Node.js 24（LTS）或更高版本
• Microsoft 账户（个人账户开箱即用；工作或学校账户需要你自己的 Azure 应用）

🚀 快速开始

无需通过终端登录，也无需设置 Azure。你只需要 Node.js 24+。

Claude Code

claude mcp add outlook --scope user -- npx -y @pepebits/outlook-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@pepebits/outlook-mcp"]
    }
  }
}

Codex (OpenAI)

codex mcp add outlook -- npx -y @pepebits/outlook-mcp

也可以将其添加到 ~/.codex/config.toml（Codex CLI 和 IDE 扩展共用）：

[mcp_servers.outlook]
command = "npx"
args = ["-y", "@pepebits/outlook-mcp"]
# env = { OUTLOOK_READ_ONLY = "true" }

在 Codex 中运行 /mcp，检查是否已连接。

其他 MCP 客户端

任何能够启动 stdio MCP 服务的客户端都可以使用：将 npx -y @pepebits/outlook-mcp 作为服务命令运行。

登录

让你的助手*“登录 Outlook”*。login 工具会返回一个 URL 和一次性代码：打开该 URL，输入代码并接受授权。更喜欢使用终端？改为运行 npx -y @pepebits/outlook-mcp auth。

默认情况下，服务使用共享的 outlook-mcp Azure 应用，该应用支持个人 Microsoft 账户（outlook.com、hotmail、live）。授权页面可能会显示发布者未经验证的警告。没有任何数据会经过我们的服务器：服务会直接从你的计算机与 Microsoft Graph 通信，你的令牌也会保留在本地令牌缓存中。有关工作或学校账户，或使用你自己的应用，请参阅使用你自己的 Azure 应用。

⚙️ 配置（.env）

.env 文件为可选项。程序会从当前目录和软件包目录中的 .env 读取变量，实际环境变量的优先级更高。你也可以通过 MCP 客户端的 env 块传递这些变量，例如：claude mcp add outlook --scope user -e OUTLOOK_TENANT=organizations -e OUTLOOK_CLIENT_ID=your-client-id -- npx -y @pepebits/outlook-mcp。

变量	默认值	描述
OUTLOOK_CLIENT_ID	共享的 outlook-mcp 应用	你自己的 Azure 应用注册的应用程序（客户端）ID（可选）。
OUTLOOK_TENANT	consumers	授权租户：consumers（个人）、organizations（工作/学校）、common（两者）或租户 GUID。
OUTLOOK_SCOPES	User.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite offline_access	登录时请求的 Graph 委托范围，以空格分隔。
OUTLOOK_TOKEN_STORE	auto	令牌缓存的存储位置：auto（可用时使用 OS 钥匙串，否则使用文件）、keychain（若没有钥匙串则失败）或 file。请参阅令牌存储。
OUTLOOK_TOKEN_CACHE	~/.config/outlook-mcp/token-cache.json	file 存储的令牌缓存文件（模式 0600）；也用于标识钥匙串条目。
OUTLOOK_READ_ONLY	false	设为 true 时，不会注册发送/移动/删除/标记/设旗工具。
OUTLOOK_DOWNLOAD_DIR	~/Downloads	附件只能写入此目录。
OUTLOOK_DEFAULT_TOP	20	列表/搜索工具的默认页大小（1-100）。
OUTLOOK_MAX_BODY_CHARS	20000	get_message 返回的正文最大字符数。
OUTLOOK_GRAPH_BASE_URL	https://graph.microsoft.com/v1.0	Graph 终结点（可更改以适配国家云）。
LOG_LEVEL	info	debug、info、warn 或 error（写入 stderr）。

🔐 身份验证

npx -y @pepebits/outlook-mcp auth      # device code sign-in; prints a URL and a code
npx -y @pepebits/outlook-mcp whoami    # silent token + GET /me
npx -y @pepebits/outlook-mcp logout    # removes accounts and deletes the token cache (keychain entry and file)

你也可以不使用终端登录。只需让你的助手*“登录 Outlook”*：

• 🔑 login 会返回一个 URL 和一次性代码。打开 URL，输入代码并确认；登录将在后台完成。
• ✅ auth_status 会告知你当前已登录、仍在等待，还是已退出登录。
• 🚪 logout 会移除缓存的账户和令牌缓存（钥匙串条目及文件）。

使用 login 并设置 force: true 可重新登录，例如在 Azure 中添加权限后。如果会话不存在或已过期，工具会返回 “未登录或会话已过期。请调用 login 工具……”。

🗝️ 令牌存储

刷新令牌是此服务持有的最敏感信息，因此默认情况下（OUTLOOK_TOKEN_STORE=auto）会将其存入操作系统钥匙串，而不是普通文件。不会使用原生 npm 依赖；服务会直接调用操作系统工具：

平台	后端	说明
macOS	通过 security CLI 使用 Keychain	服务为 outlook-mcp，账户 = 缓存路径。
Linux	通过 secret-tool（libsecret）使用 Secret Service	仅在安装了 secret-tool 且密钥环正在运行时使用；否则使用文件存储。
Windows 和其他平台	文件	~/.config/outlook-mcp/token-cache.json，模式为 0600。

• **迁移：**如果缓存文件存在且钥匙串仍为空，则会将其导入钥匙串并删除该文件。
• **回退：**在 auto 模式下，如果运行时无法使用钥匙串，服务会回退到文件存储并记录警告。OUTLOOK_TOKEN_STORE=keychain 不会回退，而是直接失败；file 则完全不会访问钥匙串。
• **机密不会出现在进程列表中：**在 Linux 上，secret-tool 会从标准输入读取机密。security add-generic-password 只能接受作为命令行参数传入的密码（其他本地进程可通过 ps 查看），因此在 macOS 上，命令会通过标准输入传给 security -i。该接口会将行截断至约 4 KB，因此缓存会以 base64 编码，并分散存储在几个较小的钥匙串条目中（<account>#0、#1，……）。
• logout（工具和 CLI）会同时删除钥匙串条目和文件。
• 在 macOS 上，如果首次访问来自不同的二进制文件，可能会显示 Keychain 提示；请点击 始终允许。

🛠️ 使用自己的 Azure 应用（可选）

默认情况下，outlook-mcp 使用共享的 outlook-mcp Azure 应用，该应用仅适用于个人 Microsoft 账户。如果需要使用工作或学校账户，或只是希望使用自己的应用，请注册自己的应用。然后设置 OUTLOOK_CLIENT_ID（以及 OUTLOOK_TENANT，见下文）。

分步操作

1. 打开 portal.azure.com，然后依次进入 Microsoft Entra ID -> App registrations -> New registration。

2. 为其命名（例如 outlook-mcp）。

3. 在 Supported account types 下选择：

   • Personal Microsoft accounts only（Outlook.com、Hotmail、Live），或
   • Accounts in any organizational directory and personal Microsoft accounts（两者均可）。
   • 如果仅用于工作或学校帐户，请选择组织帐户选项。

4. 将 Redirect URI 留空，然后点击 Register。

5. 在左侧菜单中依次进入 Manage -> Authentication -> Settings 选项卡，将 Allow public client flows 设为 Yes 并保存。

6. 依次进入 Manage -> API permissions。默认已授予 User.Read。点击 Add a permission -> Microsoft Graph -> Delegated permissions，然后添加：

   • 📬 展开 Mail 组，并勾选 Mail.ReadWrite 和 Mail.Send。
   • ⚙️ 展开 MailboxSettings 组，并勾选 MailboxSettings.ReadWrite（收件箱规则和 block_sender 需要此权限）。
   • 🔑 展开 OpenId permissions 组，并勾选 offline_access。

   然后点击 Add permissions。个人帐户无需管理员同意。

范围	用途
User.Read	登录和 whoami
Mail.ReadWrite	阅读、搜索、移动、标记和删除邮件
Mail.Send	send_mail、回复、转发和 mailto 取消订阅
MailboxSettings.ReadWrite	收件箱规则：list_rules、create_rule、delete_rule、block_sender
offline_access	刷新令牌，因此只需登录一次

💡 如果你从 0.1.0 升级，请在 Azure 中添加 MailboxSettings.ReadWrite，然后再次运行 login 并设置 force: true（或再次运行 npx -y @pepebits/outlook-mcp auth）。

💡 Azure 门户可能会以你的语言显示，因此标签可能略有不同（例如 Administrar -> Autenticación -> Configuración、Permisos de OpenId）。

7. 在 Overview 页面复制 Application (client) ID。这就是你的 OUTLOOK_CLIENT_ID。

🏢 工作或学校帐户： 将 OUTLOOK_CLIENT_ID 设为你的应用 ID，并将 OUTLOOK_TENANT 设为 organizations（或你的租户 GUID）。你的组织可能要求对邮件权限进行管理员同意。

🧰 工具参考

工具	是否修改数据	描述
login	否	启动设备代码登录；返回 URL 和代码（使用 force 再次登录）。
auth_status	否	查看已登录、等待登录或已退出状态。
logout	否	退出登录并删除本地令牌缓存。
list_folders	否	列出邮件文件夹或子文件夹（parentFolderId、includeHidden）。
list_messages	否	按时间从新到旧列出邮件，并支持筛选条件（unreadOnly、from、since、until、hasAttachments）和 nextLink 分页。
search_messages	否	使用 KQL 进行全文搜索，并支持 nextLink 分页。
get_message	否	获取完整邮件，包括收件人、标记和正文（format 为 text/html，maxChars）。
list_attachments	否	获取邮件的附件元数据。
download_attachment	否	将附件保存到 OUTLOOK_DOWNLOAD_DIR（仅写入本地；除非设置 overwrite: true，否则不会覆盖文件）。
send_mail	是	发送邮件，可附带本地附件，附件大小上限为 150 MB（3 MB 或更大的附件通过上传会话处理；如果上传失败，则不会发送邮件）。
create_draft	是	创建草稿但不发送。附件大小上限为 150 MB；上传失败会报告错误，并保留草稿。
reply_message	是	回复或回复所有人（replyAll）。
forward_message	是	转发给新收件人。
move_message	是	将邮件移至文件夹；返回新 id。接受 id 或 ids（最多 50 个）。
mark_read	是	将邮件标记为已读或未读。接受 id 或 ids（最多 50 个）。
flag_message	是	设置为 flagged、complete 或 notFlagged。接受 id 或 ids（最多 50 个）。
delete_message	是	将邮件移至“已删除邮件”，或设置 permanent: true 以永久删除。接受 id 或 ids（最多 50 个）。
bulk_action	是	对每封符合 query（KQL）或筛选条件（folderId、from、since、until、unreadOnly、hasAttachments）的邮件执行 delete、move、archive、markRead、markUnread、flag 或 unflag。默认启用 dryRun；max 默认值为 100（硬性上限为 500）。
get_unsubscribe_info	否	显示如何退订邮件所属的邮件列表（List-Unsubscribe）。
unsubscribe	是	退订邮件列表：优先使用 RFC 8058 一键退订，否则发送 mailto 请求，再否则返回链接。接受 id 或 ids（最多 50 个）。
find_newsletters	否	扫描文件夹（folderId、maxMessages 最多 2000、excludeDomains、includeNoUnsubscribe），按发件人分组，并报告邮件列表及其退订方式，按频率从高到低排列。
mail_digest	否	查看文件夹中待处理的邮件（folderId、since 默认 24h、unreadOnly 默认 true、maxMessages 最多 1000、groupBy 为 sender/none）：显示数量、高优先级邮件和已标记邮件，并按发件人分组，同时提供邮件列表提示。
list_rules	否	列出收件箱规则。
create_rule	是	根据 fromAddresses / senderContains / subjectContains 创建收件箱规则，操作为 move、delete、markRead 或 junk。
delete_rule	是	根据 id 删除收件箱规则。
block_sender	是	使用规则屏蔽 addresses 和/或 domains，将其后续邮件移至“已删除邮件”。

批量操作： 标记为“接受 id 或 ids”的工具只能接受其中一个。使用 ids 时，工具会处理最多 50 封邮件（每次处理少量邮件），不会因首个错误而停止，并返回 { results: [{ id, ok, ... | error }], succeeded, failed }。使用 id 时，响应保持不变。

凡是需要文件夹 id 的地方，均可使用以下常见文件夹名称：inbox、drafts、sentitems、deleteditems、junkemail、archive。

📬 每日摘要

询问 “我今天的收件箱里有什么待处理邮件？”，助手就会调用 mail_digest：扫描过去 24 小时内的未读邮件（可通过 since、unreadOnly、maxMessages 调整），并返回计数（总数、未读、已标记、高重要性、带附件），高重要性和已标记的邮件，以及按发件人分组的邮件，并附上最新主题和几个邮件 ID。对于排名前 20 的发件人，它会检查 List-Unsubscribe 标头，因此会将新闻简报标记为 isNewsletter，并可直接交给 unsubscribe 处理。

🧹 清理收件箱

向 Claude 提出类似 “找出塞满我收件箱的新闻简报，退订我不看的那些，并屏蔽其余的” 的请求。后台会执行以下操作：

1. find_newsletters 扫描收件箱，并列出带有 List-Unsubscribe 标头的发件人，按频率从高到低排序；每个发件人都附有 sampleMessageId 和 unsubscribe 方法（one-click、mailto 或 link）。
2. 将选定的示例邮件 ID 设为 ids，调用 unsubscribe 退订相应邮件列表。仅提供链接的发件人会返回需要在浏览器中打开的 URL。
3. 使用 addresses 或 domains 调用 block_sender 创建收件箱规则，将其后续邮件发送到“已删除邮件”。使用 delete_message 和 ids 清除收件箱中已有的邮件，并使用 list_rules / delete_rule 查看或撤销屏蔽规则。

收件箱规则需要 MailboxSettings.ReadWrite 权限（参见上方的 Azure 步骤）。不要退订垃圾邮件或网络钓鱼邮件：这会确认你的地址处于有效状态。请改为屏蔽这些发件人。

🔎 按搜索批量清理

询问 “归档所有来自 [email protected]、且在 2025 年之前收到的邮件”。bulk_action 始终从试运行开始：不会进行任何更改，并会返回匹配数量和 10 封邮件的示例。

{ "from": "[email protected]", "until": "2025-01-01", "action": "archive" }

与助手确认数量后，它会再次调用该工具，并设置 dryRun: false 来执行操作：

{ "from": "[email protected]", "until": "2025-01-01", "action": "archive", "dryRun": false }

使用 query（KQL，例如 from:shop.com hasattachments:true）或筛选字段，不能同时使用两者。最多处理 max 封邮件（默认值为 100，硬上限为 500），响应会说明结果是否被 truncated；如需处理其余邮件，请再次运行。delete 会将邮件移至“已删除邮件”（可恢复），archive 会将邮件移至“存档”文件夹，而 move 需要 destinationFolderId。失败不会中止运行：响应会为每个 ID 列出 ok 或 error。

👁️ 只读模式

设置 OUTLOOK_READ_ONLY=true，仅注册不会修改数据的工具。客户端无法使用修改数据的工具，因此完全无法调用它们。还可搭配仅使用 User.Read Mail.Read 创建的令牌缓存，以增强防护（相应设置 OUTLOOK_SCOPES，然后重新运行 npx -y @pepebits/outlook-mcp auth）。

🛡️ 安全

• 🔑 如果系统支持，令牌缓存会存储在系统钥匙串中（macOS Keychain、Linux Secret Service；参见 令牌存储）；否则会以原子方式写入本地文件，文件权限为 0600，所在目录权限为 0700。
• 🙅 不存在客户端密钥：这是使用设备代码流的公共客户端。
• 🤐 不会记录令牌和消息正文；MSAL PII 日志记录已禁用。
• 📥 附件下载仅限于 OUTLOOK_DOWNLOAD_DIR；会拒绝路径遍历。
• ⚠️ delete_message 搭配 permanent: true 时不可撤销；send_mail、reply_message 和 forward_message 会立即发送。拿不准时，优先使用只读模式或 create_draft。
• 🧠 邮件内容是不可信输入：恶意邮件可能会试图指示模型（提示词注入）。为帮助模型区分数据和指令，get_message、list_messages、search_messages、list_attachments 和 find_newsletters 的结果会将由发件人控制的文本（主题、发件人、预览、附件名称）归入 untrusted 键下，并附带说明这一点的 note。get_message 的正文会用 <untrusted_email_content> 标记括起来，并且会对内容中出现的任何标记进行处理，避免其提前闭合包裹内容。
• 🤝 服务还会发送 MCP instructions，告知客户端邮件内容不可信，且发送、删除、退订和规则变更都应征得用户确认。这些措施并非万无一失：执行这些操作时应让人工参与，或使用只读模式。

🩺 故障排除

症状	解决方法
AADSTS7000218（需要客户端断言 / 密钥）	在 Azure → Manage → Authentication → Settings 中启用 Allow public client flows。
AADSTS50020 或租户错误	帐户类型与 OUTLOOK_TENANT 不匹配。个人帐户使用 consumers，工作/学校帐户使用 organizations，两者均可使用 common，并确保应用注册支持相应的帐户类型。
“未登录或会话已过期”	请助手调用 login，或运行 npx -y @pepebits/outlook-mcp auth。
搜索返回“无效的搜索查询”	search_messages 使用 KQL，例如 from:alice subject:"report" hasattachments:true。Graph 每次搜索最多返回约 250 条结果，且结果未经排序。
移动邮件后出现“未找到邮件”	邮件移动后，邮件 ID 会发生变化。请使用 move_message 返回的 newId，或重新列出文件夹内容。
“访问收件箱规则被拒绝”	在 Azure → API permissions 中添加 MailboxSettings.ReadWrite，确保其位于 OUTLOOK_SCOPES 中，然后重新运行 npx -y @pepebits/outlook-mcp auth。
访问被拒绝 / 需要同意	添加缺少的委派权限，或请管理员授予同意。
服务无法在客户端中启动	检查 stderr 日志；如果使用自己的应用，必须通过 .env 或客户端的 env 块设置 OUTLOOK_CLIENT_ID。

🧑‍💻 开发

git clone https://github.com/Pepebits/outlook-mcp.git
cd outlook-mcp
npm install
cp .env.example .env        # optional
npm run build
npm test

在 MCP 客户端中从源代码运行：

claude mcp add outlook --scope user -- node /absolute/path/outlook-mcp/dist/index.js

使用 npm run inspect 在 MCP Inspector 中试用这些工具。

🚢 发布（维护者）

1. 将 CHANGELOG.md 中的 [Unreleased] 说明移到新版本下方，更新 package.json 和 server.json（顶层和 package 中）的版本号，然后提交并推送。
2. 为其打标签：git tag -a vX.Y.Z -m "Short summary" && git push origin vX.Y.Z。Release 工作流会运行测试、在 npm 上暂存该版本（使用 Trusted Publishing，并附带来源证明），然后创建 GitHub 发布。
3. 在 npmjs.com 上批准暂存的版本（或运行 npm stage approve <stage-id>），这需要进行双重身份验证。
4. 工作流会等待批准，将该版本列入 MCP Registry，并在 Telegram 上发布公告。如果你在约 6 小时后才批准，等待就会超时：手动运行 Release 工作流（Actions → Release → Run workflow），并填写该标签以发布公告。

🗺️ 路线图

此服务仅处理邮件；日历和其他 Microsoft 365 数据不在范围内。

目前暂无计划。欢迎提出想法：提出 issue。

🤝 贡献

欢迎提交 issue 和 pull request。

npm install
npm run typecheck
npm test
npm run build

请使用英文编写代码、注释和文档，为新行为添加测试，并且绝不记录机密信息或邮件内容。

📄 许可证

MIT