msgvault

文档 · 设置指南 · 交互式 TUI

Alpha 软件。 API、存储格式和 CLI 标志可能会在未经通知的情况下发生变化。请务必备份您的数据。

归档您一生的电子邮件。分析与搜索可在毫秒内完成，完全离线进行。

为什么选择 msgvault？

您的消息属于您。数十年的通信记录、附件和历史不应被锁定在网页界面或 API 后面。msgvault 会下载一份完整的本地副本，之后所有操作都在离线状态下进行。搜索、分析以及 MCP 服务器均可基于本地数据运行，无需网络连接。

目前支持 Gmail 和 IMAP 同步，还支持从 MBOX 导出文件和 Apple Mail (.emlx) 目录中进行离线导入。

功能

• 完整 Gmail 备份：原始 MIME、附件、标签和元数据
• IMAP 同步：从任何标准 IMAP 服务器归档邮件
• MBOX / Apple Mail 导入：从 MBOX 导出文件或 Apple Mail (.emlx) 目录中导入邮件
• 交互式 TUI：基于 DuckDB 和 Parquet 的钻取式分析，可深入查看您的整个消息历史——可连接到远程 msgvault serve 实例，也可在本地运行
• 全文搜索：使用 FTS5 引擎，支持类似 Gmail 的查询语法（from:、has:attachment、日期范围等）
• MCP 服务器：在 Claude Desktop 及其他支持 MCP 的 AI 助手上，以极快的速度访问您的完整归档
• DuckDB 分析：在 TUI、CLI 和 MCP 服务器中，对数十万封邮件进行毫秒级聚合查询
• 增量同步：History API 只抓取新增和更改的消息
• 多账户支持：在一个数据库中归档多个 Gmail 和 IMAP 账户
• 断点续传：中断的同步任务可从上次检查点继续
• 内容寻址的附件：通过 SHA-256 去重

安装

macOS / Linux:

curl -fsSL https://msgvault.io/install.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex"

安装脚本会检测您的操作系统和架构，从 GitHub Releases 下载最新版本，验证 SHA-256 校验和，并安装二进制文件。您可以在运行前查看脚本（bash、PowerShell），或者直接从 GitHub 下载发布版二进制文件。

如果您想从源码构建（需要 Go 1.25+ 和 C/C++ 编译器以支持 CGO 并静态链接 DuckDB）：

git clone https://github.com/wesm/msgvault.git
cd msgvault
make install

Conda-Forge:

您可以通过 Pixi 或 Conda 从 conda-forge 安装 msgvault：

pixi global install msgvault
conda install -c conda-forge msgvault

快速入门

先决条件： 在添加账户之前，您需要一个 Google Cloud OAuth 凭证。 请按照 OAuth 设置指南 创建一个 (~5 分钟)。

msgvault init-db
msgvault add-account you@gmail.com          # 打开浏览器进行 OAuth 授权
msgvault sync-full you@gmail.com --limit 100
msgvault tui

命令

命令	描述
init-db	创建数据库
add-account EMAIL	授权 Gmail 账户（使用 --headless 可用于服务器）或添加 IMAP 账户
sync-full EMAIL	全量同步（--limit N、--after/--before 用于指定日期范围）
sync EMAIL	只同步新增或更改的消息
tui	启动交互式 TUI（--account 用于筛选，--local 强制使用本地数据）
search QUERY	搜索消息（--account 用于筛选，--json 用于机器输出）
show-message ID	查看完整消息详情（--json 用于机器输出）
mcp	启动 MCP 服务器，用于 AI 助手集成
serve	运行守护进程，定时同步并提供 HTTP API 供远程 TUI 使用
stats	显示归档统计信息
list-accounts	列出已同步的邮箱账户
verify EMAIL	验证归档完整性，与 Gmail 对比
export-eml	将消息导出为 .eml 文件
import-mbox	从 MBOX 导出文件或包含 MBOX 文件的 .zip 文件中导入邮件
import-emlx	从 Apple Mail 目录树中导入邮件
build-cache	重建 Parquet 分析缓存
update	更新 msgvault 到最新版本
setup	交互式首次运行配置向导
repair-encoding	修复 UTF-8 编码问题
list-senders / list-domains / list-labels	浏览元数据

更多详细信息请参阅 CLI 参考。

从 MBOX 或 Apple Mail 导入

您可以从提供 MBOX 导出功能的邮件服务商，或从本地的 Apple Mail 数据目录中导入邮件：

msgvault init-db
msgvault import-mbox you@example.com /path/to/export.mbox
msgvault import-mbox you@example.com /path/to/export.zip   # 包含 MBOX 文件的 ZIP 文件
msgvault import-emlx                                        # 自动发现 Apple Mail 账户
msgvault import-emlx you@example.com ~/Library/Mail/V10     # 指定路径

配置

默认情况下，所有数据都存储在 ~/.msgvault/ 中（可通过 MSGVAULT_HOME 环境变量覆盖）。

# ~/.msgvault/config.toml
[oauth]
client_secrets = "/path/to/client_secret.json"

[sync]
rate_limit_qps = 5

有关所有选项，请参阅 配置指南。

多个 OAuth 应用程序（Google Workspace）

某些 Google Workspace 组织要求在其内部使用特定的 OAuth 应用程序。 要使用多个 OAuth 应用程序，可以在 config.toml 中添加命名的应用程序：

[oauth]
client_secrets = "/path/to/default_secret.json"   # 用于个人 Gmail

[oauth.apps.acme]
client_secrets = "/path/to/acme_workspace_secret.json"

然后在添加账户时指定应用：

msgvault add-account you@acme.com --oauth-app acme
msgvault add-account personal@gmail.com              # 使用默认应用

如果要将现有账户切换到不同的 OAuth 应用程序：

msgvault add-account you@acme.com --oauth-app acme   # 重新授权

MCP 服务器

msgvault 内置了一个 MCP 服务器，允许 AI 助手搜索、分析和阅读您归档的消息。将其连接到 Claude Desktop 或任何支持 MCP 的助手，即可通过对话方式查询您的完整消息历史。有关设置说明，请参阅 MCP 文档。

守护进程模式（NAS/服务器）

将 msgvault 作为长期运行的守护进程，用于计划同步和远程访问：

msgvault serve

在 config.toml 中配置计划同步：

[[accounts]]
email = "you@gmail.com"
schedule = "0 2 * * *"   # 每天凌晨2点（cron）
enabled = true

[server]
api_port = 8080
bind_addr = "0.0.0.0"
api_key = "your-secret-key"

通过配置 [remote].url，TUI 可以连接到远程服务器。如果已配置远程服务器，可使用 --local 强制使用本地数据库。有关 HTTP API 的参考信息，请参阅 docs/api.md。

文档

• 设置指南：OAuth、首次同步、无头服务器
• 搜索：查询语法和运算符
• 交互式 TUI：快捷键、视图、删除暂存
• CLI 参考：所有命令和标志
• 多账户：管理多个 Gmail 账户
• 配置：配置文件和环境变量
• 架构：SQLite、Parquet 和附件存储
• MCP 服务器：AI 助手集成
• 故障排除：常见问题及解决方法
• 开发：贡献、测试、构建

社区

加入 msgvault Discord，提问、分享反馈、报告问题，并与其他用户交流。

开发

git clone https://github.com/wesm/msgvault.git
cd msgvault
make install-hooks  # 安装 pre-commit 钩子（需要 prek）
make test           # 运行测试
make lint           # 运行 linter（自动修复）
make install        # 构建并安装

pre-commit 钩子由 prek 管理（brew install prek）。

许可证

MIT 许可证。详情请参阅 LICENSE 文件。

msgvault 快速上手指南

msgvault 是一款开源的本地邮件归档与分析工具，支持 Gmail、IMAP、MBOX 及 Apple Mail 数据导入。它能在离线环境下提供毫秒级搜索、数据分析，并支持通过 MCP 协议与 AI 助手集成。

注意：当前为 Alpha 版本，API 和存储格式可能变更，请务必备份重要数据。

环境准备

系统要求

• 操作系统：macOS、Linux 或 Windows (PowerShell)
• 架构：自动检测并适配当前系统架构

前置依赖

1. Google Cloud OAuth 凭证（仅限 Gmail 用户）：
   • 在添加 Gmail 账户前，需先在 Google Cloud Console 创建 OAuth 凭证。
   • 请参考官方 OAuth 设置指南（约需 5 分钟）。
2. 编译源码可选依赖（仅当从源码构建时）：
   • Go 1.25+
   • C/C++ 编译器（用于 CGO 和静态链接 DuckDB）

安装步骤

方式一：一键脚本安装（推荐）

macOS / Linux:

curl -fsSL https://msgvault.io/install.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex"

脚本会自动下载最新 release、校验 SHA-256 并安装二进制文件。

方式二：包管理器安装

使用 Conda-Forge (Pixi 或 Conda):

pixi global install msgvault
# 或
conda install -c conda-forge msgvault

方式三：从源码构建

git clone https://github.com/wesm/msgvault.git
cd msgvault
make install

基本使用

以下流程演示如何初始化数据库、授权 Gmail 账户、同步邮件并启动交互式界面。

1. 初始化数据库

创建本地存储数据库：

msgvault init-db

2. 添加账户

授权你的 Gmail 账户（将自动打开浏览器进行 OAuth 认证）：

msgvault add-account you@gmail.com

注：若是 IMAP 账户或无图形界面服务器，可添加 --headless 参数。

3. 同步邮件

执行全量同步（示例中限制同步最近 100 封邮件以快速测试）：

msgvault sync-full you@gmail.com --limit 100

移除 --limit 参数即可同步所有历史邮件。

4. 启动交互式界面 (TUI)

launches 基于 DuckDB 的分析界面，可查看统计信息及进行搜索：

msgvault tui

其他常用命令

• 搜索邮件：

  msgvault search "from:github has:attachment"
  

• 启动 MCP 服务（供 Claude Desktop 等 AI 助手调用）：

  msgvault mcp
  

• 导入 MBOX/Apple Mail 数据：

  msgvault import-mbox you@example.com /path/to/export.mbox
  msgvault import-emlx you@example.com ~/Library/Mail/V10
  

所有数据默认存储在 ~/.msgvault/ 目录下，可通过 MSGVAULT_HOME 环境变量自定义路径。详细配置请参考 配置指南。