Mail-MCP

Mail-MCP

一个小巧、专注的 MCP 服务，让 Claude（Claude Desktop、Cowork、Claude Code 或任何 MCP 客户端）通过 Microsoft Graph 管理个人 Outlook.com / Hotmail / Live 邮箱：读取和搜索邮件、将邮件归档到文件夹、删除邮件，以及取消订阅新闻邮件。

专为一项任务而打造：安全地借助 AI 助手清理堆积如山的个人收件箱。

工具

共 9 个工具，名称均以 mail_ 开头：

工具	功能
mail_list_folders	文件夹树，包含总数 / 未读数
mail_create_folder	创建文件夹（幂等）
mail_search	列出 / 搜索邮件（发件人、日期范围、未读、全文），支持分页
mail_get_message	获取单封邮件的完整内容 + 检测到的取消订阅选项
mail_senders_summary	按发件人汇总整个文件夹：邮件数量、最新邮件、可用的取消订阅方式
mail_move	将最多 500 封邮件移动到文件夹
mail_delete	默认移至“已删除邮件”；设置 permanent: true 可彻底删除
mail_bulk_by_sender	移动或删除某个发件人的所有邮件（支持 dryRun）
mail_unsubscribe	RFC 8058 一键 POST → mailto: 邮件 → 否则返回一个供助手在浏览器中打开的 URL

设计选择：

• 默认安全。 删除操作会将邮件移至“已删除邮件”（在 Outlook 中可见且可恢复）。彻底删除需要显式设置标记。批量操作支持 dryRun。
• 适用于大型邮箱，效率出色。 mail_senders_summary 可在几秒内扫描数千封邮件（每页 1,000 封，最少化 $select），并且只通过 $batch 获取主要发件人的邮件头。
• 没有通用发送工具。 Mail.Send 权限仅用于发送 mailto: 取消订阅请求。
• 每个工具都提供严格的输入模式、输出模式和 MCP 注释（readOnlyHint、destructiveHint 等），因此宿主可以自动批准只读调用。

要求

• Node.js 22 或更新版本。
• 个人 Microsoft 账户（outlook.com、hotmail.com、live.com、msn.com）。
• 免费的 Microsoft Entra 应用注册（只需 5 分钟，见下文）。个人账户已于 2024 年 9 月停用基于密码的 IMAP，因此 OAuth 应用是唯一受支持的接入方式。

1. 在 Microsoft Entra 中注册应用（一次性，免费）

公共客户端应用不需要 Azure 订阅。

1. 前往 https://entra.microsoft.com，使用个人 Microsoft 帐户登录。
2. Identity → Applications → App registrations → New registration。
3. 填写：
   • Name：Mail-MCP
   • Supported account types：Personal Microsoft accounts only
   • Redirect URI：平台选择 Mobile and desktop applications，值为 http://localhost
4. 点击 Register，复制 Application (client) ID（xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）。
5. 在 Authentication 下，确保 http://localhost 列在 "Mobile and desktop applications" 下，并且 Allow public client flows 为 Yes。
6. 在 API permissions 下，添加 Microsoft Graph 委派权限：Mail.ReadWrite、Mail.Send、User.Read、offline_access。无需管理员同意；你会在首次登录时同意。

不会创建客户端密钥：该服务是使用带 PKCE 的授权码流的公共客户端。

2. 登录

无需安装，npx 会从 npm 获取软件包（@rixtay/mail-mcp，安装的命令为 mail-mcp）：

MAIL_MCP_CLIENT_ID=<your-client-id> npx -y @rixtay/mail-mcp login

或者从克隆的仓库运行：

git clone https://github.com/Rixtayz/Mail-MCP.git
cd Mail-MCP
npm install && npm run build
MAIL_MCP_CLIENT_ID=<your-client-id> npm run login

login 命令会打开系统浏览器，让你使用 Microsoft 帐户登录，然后将令牌缓存存储在 ~/.mail-mcp/token-cache.json（文件模式为 600）。令牌会在滚动的 90 天内静默刷新。如果某个工具返回 "Token expired"，请再次运行同一命令。

环境变量	用途
MAIL_MCP_CLIENT_ID	必需。 第 1 步中的 Application (client) ID
MAIL_MCP_CACHE_PATH	可选。令牌缓存位置

3. 连接到 Claude Desktop / Cowork

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json），也可通过 Settings → Developer → Edit Config 打开该文件。

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "@rixtay/mail-mcp"],
      "env": {
        "MAIL_MCP_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

如果 Claude Desktop 找不到 npx（它不会继承 shell 的 PATH），请改用绝对路径："command": "/absolute/path/to/node"、"args": ["/absolute/path/to/Mail-MCP/dist/index.js"]。

完全退出 Claude Desktop 后重新启动。日志位置：~/Library/Logs/Claude/mcp-server-mail.log。

Cowork 仅在本地会话中运行本地 MCP 服务，不会在云端会话中运行。

4. 连接到 Claude Code

claude mcp add --scope user --env MAIL_MCP_CLIENT_ID=<your-client-id> --transport stdio mail -- npx -y @rixtay/mail-mcp

5. 提示词示例

• “总结我收件箱中的发件人，并标出新闻邮件。”
• “取消订阅所有我六个月内没有打开过的新闻邮件，然后将它们的邮件移到‘已删除邮件’。”
• “创建一个 Invoices 文件夹，并将 [email protected] 发来的所有邮件移到其中。”
• “显示我银行发来的最新邮件。”

典型工作流：mail_senders_summary → 助手提出列表，你确认 → 对每封新闻邮件运行 mail_unsubscribe(lastMessageId)（当返回结果为 method: "browser" 时，助手会在其浏览器中打开 URL 并完成后续操作）→ mail_bulk_by_sender(action: "delete")。

开发

npm test          # vitest: header parsing, Graph retry/batch/pagination, service with a mocked Graph
npm run typecheck
npm run inspect   # MCP Inspector against dist/index.js

目录结构：

src/index.ts          CLI entry point: `mail-mcp` serves stdio, `mail-mcp login` signs in
src/login.ts          interactive sign-in flow
src/server.ts         builds the McpServer and registers the tools
src/auth.ts           MSAL public client, file-based token cache
src/graph.ts          Graph client: bearer auth, 429/503 retry, pagination, $batch in chunks of 20
src/mail.ts           business logic (folders, search, sender summary, move/delete, unsubscribe cascade)
src/unsubscribe.ts    List-Unsubscribe / List-Unsubscribe-Post parsing, RFC 8058 one-click POST
src/tools/*.ts        tool definitions (zod v4 schemas, annotations)

技术栈：@modelcontextprotocol/server v2、zod v4、@azure/msal-node v6、html-to-text。

注意事项

• 每当邮件更换文件夹时，邮件 ID 都会改变。mail_move 和 mail_delete 会返回旧 ID → 新 ID 的映射。
• 普通删除操作会将邮件移到“已删除邮件”。Graph 自身的 DELETE 会将邮件放入 Outlook 中不可见的“可恢复邮件”文件夹，因此这里特意不使用。
• Microsoft 对 Outlook 的限制是每个邮箱每 10 分钟 10,000 个请求，最多 4 个并发请求。批次会串行处理，并在遇到 429 时重试。
• 带有 query（全文搜索）的 mail_search 不能与其他筛选条件组合使用（Graph 的限制），且结果最多只有几百条。
• 取消订阅是否生效由发件人决定。一键退订和 mailto: 会发送请求；其余操作由助手的浏览器完成。
• authority 为 login.microsoftonline.com/consumers。如果使用 common，个人帐户的刷新令牌在首次刷新后会被拒绝。

参与贡献

欢迎提交错误报告、修复和专注于特定功能的新工具：请参阅 CONTRIBUTING.md。请勿在问题中粘贴真实邮件内容、地址或令牌。发现服务可能泄露邮件或令牌，或未经请求就执行操作？请按照 SECURITY.md 中的说明私下报告。

发布历史：CHANGELOG.md。

许可证

MIT