mailwarden 是一个原生 Gmail MCP 服务器，旨在为 AI 助手提供可靠、完整的邮箱分类与管理能力。它直接与实时 Gmail API 通信，不依赖缓存快照，并针对 Gmail 线程索引可能返回过时已读状态的问题，对搜索结果进行实时标签复核。
用途
mailwarden 用于让 AI 助手安全地操作 Gmail 邮箱，包括搜索、读取、打标签、归档、移至垃圾箱、下载附件，以及将邮件线程“稍后处理”（snooze）到指定日期后重新出现在收件箱。它定位为通用的 Gmail 能力层，用户可将自己的规则和逻辑保留在 AI 客户端中，而非服务器内。
主要能力
- 邮箱侧 snooze：将线程归档，并在指定日期后重新回到收件箱。基于带日期的标签和扫描实现，可在任何客户端使用，在 Gmail 中可见，且重启后依然有效。
- 可信搜索：Gmail 的 threads.list 可能因线程级已读状态过时而返回错误结果。mailwarden 对每个命中项根据其实时标签重新验证，丢弃索引的误报。支持 pageToken / nextPageToken 分页。
- 发件人认证：get_thread 报告接收服务器记录的 SPF/DKIM/DMARC 结果，仅读取 Gmail 自身在 mx.google.com 下写入的报告，并说明通过的 DKIM 签名是否属于 From 域，未检查时标记为 unchecked。
- 批量操作：bulk_modify 以每 API 请求 1000 封邮件的规模归档或打标签，支持按块报告部分成功。snooze 扫描使用相同的批量路径。
- 结构化输出：每个工具声明 outputSchema，并返回经过验证的 structuredContent 以及围栏 JSON 文本。失败也结构化，包含错误码和可重试标志。
- 安全设计：无发送工具，可选只读模式，无遥测，默认不开放端口，下载路径防符号链接，输出防注入。所有 Gmail 请求经过出口检查点，拒绝 messages.send、所有草稿端点、永久删除和转发设置。唯一例外是 unsubscribe / bulk_unsubscribe（manage 层级）会联系邮件自身标头中指定的退订端点。
- 真实邮件兼容：解码 RFC 2047 标头，按声明字符集解码正文，对 429/5xx 使用指数退避重试。
- what_changed：read 层级工具，根据 Gmail 自身事件日志回答“自上次查看以来有什么变化”，只需传入之前调用或 get_profile 返回的 historyId，返回到达、离开、标签增减以及下一个 id。不存储邮箱镜像或索引。
使用方式
mailwarden 作为 MCP 服务器运行，需在 AI 客户端中配置。它提供不同层级（如 read、manage），read 层级使用 gmail.readonly 范围，manage 层级使用 gmail.modify 范围。可通过 --read-only 切换 OAuth 流程为只读范围。仓库中包含演示脚本（node scripts/probe-reverify.mjs 等），可在克隆仓库后运行，无需 Gmail 账户即可验证搜索复核行为。
适用场景
- 让 AI 助手对 Gmail 邮箱进行日常分类、归档、打标签和 snooze 管理。
- 需要发件人认证信息以判断邮件真实性的场景。
- 需要批量处理大量邮件但要求部分成功报告的场景。
- 与 Workspace 套件服务器（如 taylorwilsdon/google_workspace_mcp）配合使用，将邮件部分交给 mailwarden，从而避免套件服务器持有可发送邮件的凭证。
限制
- 不提供发送、回复、转发、草稿或永久删除工具。
- 批量工具（bulk_modify、create_filter 的 applyToExisting 扫描）作用于索引返回的结果，不进行逐条实时复核；会报告 unverifiedPredicates 字段说明哪些条件基于索引。crossCheck 选项可进行二次检查，但一致性不构成证据。
- 过滤器扫描不报告 unverifiedPredicates 字段，需以 verify: true 了解实际更改。
- 关于收费、价格、平台支持等具体信息，资料中暂未提供。
