mail-index

mail-index

mail-index 会将整个收件箱的预览下载到你的设备，并在你使用时智能获取重要邮件的全文。借助这个本地索引，你的 AI Agent 可以对整个邮箱进行真正的摘要和回忆，而不再受困于 Gmail 的搜索栏。

它通过本地 MCP 服务运行，因此任何 Agent（Claude、Codex 以及任何 MCP 客户端）都可以查询。本地优先——默认索引不会离开你的设备。需要始终在线连接器的运维人员，也可以在自己的 Cloudflare 账户中部署可选的单租户远程 Worker 部署；mail-index 不提供托管服务。 默认只读——除非你明确选择启用归档和标签修改（需重新进行 gmail.modify 授权），或在远程部署中启用草稿（需重新进行 gmail.compose 授权），否则它绝不会修改邮件。它绝不会发送或删除邮件。这两个可选授权范围在令牌层级都具备发送邮件的能力，因此这一保证由代码强制执行（Gmail runner 中的发送防护，以及 test/drafts.test.ts），而非由授权范围保证。请参阅 ADR-0007 和 ADR-0011。

_{提出一个含糊的问题 → 一次本地 MCP 调用 → 按相关度排序、优先显示摘要的回答。 交互版本 →}

状态：v1.5 — 已发布。 渐进式同步、通信关系图谱、兴趣引擎、内容整理、完整的 MCP 功能，以及写回工作流均已构建并通过测试；mail-index 已在 npm 上线，并提供 .mcpb bundle。 仍在进行中：捆绑的 Option A OAuth 客户端和签名的一键安装程序。架构说明见 docs/PLAN.md；请从 docs/INSTALL.md 开始；每个版本的记录见 CHANGELOG.md。 [!TIP] v1.5 新增 — 可选的远程部署。 mail-index 现在也可以作为你自己的账号中的单租户 Cloudflare Worker运行：始终在线，按 cron 同步，并可供远程 Agent 通过经过身份验证的 MCP 访问（另提供一个小型 A2A 接口）。它提供与本地服务相同的工具注册表，底层使用通过相同 FTS 排名一致性测试套件的 D1 存储驱动；它还可以主动推送——触发规则会匹配新到的邮件，并发送已签名的 Webhook。较长的 O(N) 操作会变成排队的 Job，而不是交还命令。你可以直接从现有的本地索引，通过 mail-index export → 导入 D1，为全新的部署预置数据，这样启动时就已包含你的历史邮件索引。本地 CLI + stdio 路径保持不变，仍是默认方式，而且 mail-index 仍不运营任何托管服务——Worker 是由你部署到自己拥有的基础设施上的代码。 参见 docs/INSTALL-worker.md、 docs/WORKER-SEED.md、 ADR-0008。

本地也有新增功能：每个 MCP 响应都会附带一个新鲜度信息块，任何过期读取现在都会自动触发后台同步（之前只有摘要组合操作会这样）。

提示

v1.4 新增 — 可选启用邮箱写入 + 易读标签。 mail-index 可以直接在 Gmail 中归档邮件并编辑其标签——通过 archive / label CLI 命令，以及 gog 和 gws 适配器中的 archive_message / modify_labels MCP 工具实现。默认仍为只读：在你选择通过 gmail.modify 授权之前，无法执行写入（mail-index 绝不会发送或删除邮件；该权限范围允许发送邮件，因此代码中设有保护措施，详见 ADR-0011）——可通过 mail-index setup --account <email> --enable-writes 或随附的 scripts/enable-writes.sh 为每个账号单独启用。标签在各处均显示为易读名称（索引会缓存 Gmail 的标签目录，并双向解析 Label_3546… → "Expedition Insure"），而且你可以将易读标签名称传给 label --add/--remove。 参见 ADR-0007。

---

工作原理

1. 渐进式同步 — 几分钟内获取整个邮箱的元数据；按需获取邮件正文。
2. 图谱 — 联系人、域名和邮件会话；分析你个人邮件（非批量邮件）中的中心性和社群。
3. 兴趣度 — 根据已读、回复、加星标和重要性信号，为每位联系人计算互动分数。这是供你整理的_种子_，而非自主决策。
4. 整理 — 由你（通过 Agent 或 CLI 向导）确认哪些人或内容重要；该画像会决定获取哪些邮件正文。
5. 查询 — 你的 Agent 搜索、遍历图谱并读取重要邮件，全部通过 MCP 在本地完成。

_{重要邮件会预热到本地索引中；MCP 从索引读取，只有在需要的正文尚未存入索引时才会再次访问 Gmail。 交互版本 →}

## 快速开始

需要 Node 24+ 和一个 Gmail MailSource 适配器——gog（推荐） 或 gws。读取 Gmail 需要 Google OAuth 客户端，可通过两种 方式获取：使用 mail-index beta 客户端（完全跳过 Google Cloud； 申请访问权限 加入约 100 人的测试名单），或使用你自己的 Google Cloud 客户端（无名额 限制，也无需申请——我们会引导你完成设置）。请参阅 docs/INSTALL.md §2 和 docs/oauth-and-verification.md。

npm install -g mail-index                    # or: pnpm add -g mail-index

mail-index init                              # scaffold the config
# …connect a mailbox (own OAuth client, read-only) — see docs/INSTALL.md §2 / agent-install.md…
mail-index sync  --account personal --since 6mo
mail-index graph build --account personal
mail-index search "that contract we discussed"

（更喜欢从源码安装？执行 git clone …、pnpm install && pnpm build，然后 通过 node dist/cli/index.js … 运行二进制文件。）

添加到 Claude

只需一步即可注册 MCP 服务，但首先仍需连接邮箱（请参阅操作指南）。.mcpb/claude mcp add 只会添加服务—— 不会安装适配器、登录或同步。

• Claude Code： claude mcp add --transport stdio mail-index -- npx -y -p mail-index mail-index-mcp （在 Windows 上，前面加上 cmd /c：… -- cmd /c npx -y -p mail-index mail-index-mcp — 单独使用 npx/.cmd 无法启动。请参阅 docs/INSTALL.md §7。）
• 任何 MCP 客户端（手动）：

  { "mcpServers": { "mail-index": { "command": "mail-index-mcp" } } }
  

• Claude Desktop： 下载 .mcpb bundle 并双击打开（测试期间尚未签名——你可能需要在系统设置 / Windows SmartScreen 中允许安装）。该 bundle 独立完整 （自带依赖，由 Claude Desktop 内置的 Node 运行——无需 npx、网络或系统级 Node），因此在 Windows/macOS/Linux 上的安装方式完全相同。能同时安装适配器、 登录并同步的一体化签名安装程序仍在开发中；目前没有 claude:// 安装链接。

教会你的 Agent 常用操作。 MCP 服务已告知 Agent 何时使用它 （购买、收据、预订、“谁说了什么”、“帮我补上近况”），仓库还附带了 Claude Agent Skill ，其中包含常见操作指南（查找购买记录、了解近况、查找联系人邮件、 总结发件人）。将其添加到 Claude Code/Desktop：

mkdir -p ~/.claude/skills && cp -R skills/mail-index ~/.claude/skills/

完整操作指南（身份验证、整理、丰富信息、计划同步、桌面应用注意事项）→ docs/INSTALL.md。通过 Agent 指导设置 → docs/agent-install.md。

预期情况 — 时间与存储

索引会保留每封邮件的元数据，只在确有价值时保存全文，因此其大小随邮件_数量_增长， 而非随邮箱大小增长——约为 Gmail 的 1.5%。首次同步速度约为每分钟 50 封邮件（仅首次如此，之后为增量同步）；搜索即时完成。 先用 --since 1mo，几分钟内即可见效，之后再扩大范围。容量表与增长 路径 → docs/INSTALL.md §9。

为什么它比 Gmail 搜索更轻量

原生 Gmail-API MCP 是基于查询的查找工具——需要精确查询，每次调用都要进行一次网络 往返，还会把原始载荷全部塞进模型上下文。mail-index 通过本地回忆索引回答_模糊_问题。在真实邮箱上的 100 个问题测试中，它用少 15 倍的 token 回答了所有问题——而在基于查询的 MCP 完全没有对应基本功能的场景中，这一差距还会扩大： 例如总结、人际关系和承诺事项。

各类别对照表、单封邮件阅读对比、逐工具全景分析，以及复现方法 → docs/COMPARISON.md。

技术栈

TypeScript · node:sqlite（无原生依赖）· SQLite FTS5 · Graphology · @modelcontextprotocol/sdk。Node 24+。可插拔的 MailSource 适配器；内置两种 Gmail 传输方式——gog（推荐）和 Google 的 gws。

CLI

提供两个可执行程序：mail-index（CLI）和 mail-index-mcp（stdio MCP 服务）。

mail-index init                          Scaffold the operator config + data dir
mail-index sync    --account <a> [--since 30d|1mo] [--all] [--query <q>] [--limit N]
mail-index sync    --all-accounts        Sync every account by its policy presets
mail-index enrich  --account <a> [--profile | --rule direct|all] [--sender <s>] [--match <fts>] [--limit N]
mail-index graph   build [--account <a> | --all-accounts]
mail-index curate  [--account <a>]       Interactive curation wizard (no-agent fallback)
mail-index compact [--account <a>] [--now]   Demote summarized bulk bodies (ADR-0003)
mail-index search  <terms> [--account <a>] [--limit N] [--enrich]
mail-index show    <account:message-id>  Print a message (auto-enriches a meta row)
mail-index open    <account:message-id>  Print the provider web URL (no fetch)
mail-index archive <account:message-id>  Archive (drop INBOX) — opt-in write; needs gmail.modify
mail-index label   <account:message-id> [--add <l>]... [--remove <l>]...  Opt-in write; needs gmail.modify
mail-index status  [--json]              Per-account freshness + counts

默认关闭写入功能。使用 mail-index setup --account <email> --enable-writes（或附带的 scripts/enable-writes.sh <email>）并授予 gmail.modify 权限，即可为账户启用归档和标签编辑。在远程 Deployment 上，create_draft 是第三种可选写入操作，需单独授予 gmail.compose 权限（&drafts=1）才能启用。这两种权限范围在令牌层面都可以发送邮件；mail-index 从不发送或删除邮件，因为 Gmail 运行器会拒绝发送操作路径，而且 test/drafts.test.ts 会在任何新增此类操作时导致 CI 失败。详见 ADR-0007 和 ADR-0011。

文档

• docs/INSTALL.md — 通用入门指南（安装、 验证 MailSource、初始化、同步、整理、丰富数据、添加 MCP 服务、 定时同步示例）。
• docs/MCP.md — 面向 Agent 集成者的 18 个工具 MCP 参考文档：参数、紧凑的结果格式、index_as_of 新鲜度
  • 命令交接约定。
• docs/ADAPTERS.md — MailSource 合约，以及如何编写并进行合约测试来验证新适配器（gws、gog、gmail-rest）。
• docs/INSTALL-worker.md — 将可选的单租户远程 Worker 部署到你自己的 Cloudflare 账户：D1 / Queue / KV 资源、密钥、运维人员允许列表、连接 Agent，以及验证清单。
• docs/STAFF-SENT-EVIDENCE.md — 已禁用的私有 SENT 证据新鲜度服务、调用方/授权边界和启用前提条件。
• docs/WORKER-SEED.md — 从现有本地索引为全新 Deployment 的 D1 初始化数据（mail-index export → import），而非重新同步 Gmail 中的整个邮箱。
• docs/PLAN-worker.md — 远程 Deployment 设计： 已锁定的决策、里程碑，以及本地与远程的兼容性约束。
• CHANGELOG.md — 每个已发布版本的变更内容。
• docs/PLAN.md — 架构、数据模型和关键决策（ADR 摘要）。
• SECURITY.md + docs/THREAT-MODEL.md — 隐私立场、信任边界、提示词注入应对策略，以及“自行验证我们的声明”操作手册。仅限本地的承诺由 CI 中的出站流量防护测试强制执行——核心代码（src/）不会发起网络调用；唯一例外是可选择退出的启动垫片自动更新程序（bin/selfupdate.mjs，会限频检查 npm 版本；设置 MAIL_INDEX_NO_AUTOUPDATE=1 可禁用），并由同一防护机制审计。

关于

由 Unsold Group 构建——一家旅游与保险科技公司，致力于打造以 AI 为核心运营模式的基础：本地优先、Agent 原生的基础设施，为 AI 提供真实、可查询的工作上下文。mail-index 是其中的一部分——为 Agent 提供持久的邮箱记忆，而无需把邮箱的钥匙交给它们。

了解更多：unsold.group/al

项目增长

反馈与联系

本地安装不会收集遥测数据。只有在自托管远程部署的运营者设置了 POSTHOG_PROJECT_TOKEN 时，才会发送工具使用元数据（绝不会发送参数或结果） （INSTALL-worker.md）。我们只知道您告诉我们的信息，因此诚挚欢迎您提供反馈：

• 💬 讨论区 — 提问、分享想法和使用方式
• 🐞 报告 Bug · 💡 请求新功能
• 🔒 安全与隐私问题 → SECURITY.md（私密）
• 🌐 unsold.group/al

您也可以直接在 Agent 中说 "report a mail-index bug" — MCP 服务会为 Agent 提供 GitHub 链接，供您提交问题（它本身不会发送任何内容）。请参阅 SUPPORT.md。

许可证

MIT