mbox-mcp

mbox-mcp

用于本地邮件归档的 MCP 服务。将它指向 Google Takeout 导出的 .mbox 文件或 .eml 文件夹，然后向 Claude 提问，例如：

• “在这个归档中，我给谁发过最多邮件？”
• “找出房东提到续租的那封邮件。”
• “总结我在 2026 年初与 [email protected] 的往来邮件。”

所有内容都保留在你的设备上。 无需 OAuth、应用专用密码、IMAP 连接或云服务。其他所有邮件 MCP 服务都会连接到实时账户，而本服务会读取你已有的归档文件；对于 Takeout 导出中保存的 15 年 Gmail 邮件，这正是你需要的方式。

快速开始

Claude Code

claude mcp add mbox -- npx -y mbox-mcp

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mbox": {
      "command": "npx",
      "args": ["-y", "mbox-mcp"]
    }
  }
}

然后：“打开 C:\Takeout\Mail\All mail Including Spam and Trash.mbox，告诉我里面有什么。”

工具

工具	功能
open_archive	为 .mbox 文件或 .eml 目录建立索引：邮件数量、日期范围、主要发件人
search_messages	按关键词、发件人、主题、日期范围搜索，还支持有界的正文文本搜索
get_message	完整解析一封邮件：解码后的正文、邮件头、附件名称和大小

为大型归档而构建

Takeout mbox 文件通常有数 GB，包含 10 万封以上邮件。本设计会延迟读取，只读取必要内容：

• 流式索引 — 以 8 MiB 分块单次遍历，记录字节偏移量；解析邮件封套时，只会在内存中保留当前邮件开头的 16 KiB（发件人、主题、日期、RFC 2047 解码）。
• 按需完整解析 MIME — 读取邮件时只解析该邮件（postal-mime：嵌套多部分内容、字符集、quoted-printable/base64）。附件只列出名称和大小，不会放入上下文。
• 如实进行正文搜索 — body_query 只对已匹配邮件封套筛选条件的邮件进行完整解析，在扫描数量达到上限时停止，并报告扫描数量，以便模型知道应先按发件人或日期缩小范围。
• 支持检测陈旧缓存 — 每个进程只为归档建立一次索引；文件发生变化时会重新建立索引。

说明与限制

• mbox 变体：Takeout 和 Thunderbird 会生成 mboxrd（正文中的 From 行会转义为 >From ），因此可以正确拆分。正文中未转义 From 行的纯 mboxo 归档可能会被过度拆分。
• 不会返回或写入任何附件内容。
• 目前不支持 PST/OST 和 Maildir。

开发

npm install
npm test                 # offline tests — synthetic archives built in-suite
npm run build            # tsc → dist/
node scripts/smoke.mjs   # end-to-end: generates an archive, drives the server over stdio

架构：src/archive.ts（流式索引器、邮件头解码、邮件封套筛选）和 src/reader.ts（逐封邮件 MIME 解析）是纯逻辑；src/index.ts 负责 MCP 接线。测试套件包含一项分块边界属性测试：使用极端的 17 字节分块进行索引，必须与整文件读取生成相同的索引。

许可证

MIT