Documentation · Setup Guide · Interactive TUI
Alpha software. APIs, storage format, and CLI flags may change without notice. Back up your data.
Archive a lifetime of email. Analytics and search in milliseconds, entirely offline.
Your messages are yours. Decades of correspondence, attachments, and history shouldn't be locked behind a web interface or an API. msgvault downloads a complete local copy and then everything runs offline. Search, analytics, and the MCP server all work against local data with no network access required.
Currently supports Gmail and IMAP sync, plus offline imports from MBOX exports and Apple Mail (.emlx) directories.
- Full Gmail backup: raw MIME, attachments, labels, and metadata
- IMAP sync: archive mail from any standard IMAP server
- MBOX / Apple Mail import: import email from MBOX exports or Apple Mail (.emlx) directories
- Interactive TUI: drill-down analytics over your entire message history, powered by DuckDB over Parquet — connects to a remote
msgvault serveinstance or runs locally - Full-text search: FTS5 with Gmail-like query syntax (
from:,has:attachment, date ranges) - MCP server: access your full archive at the speed of thought in Claude Desktop and other MCP-capable AI agents
- DuckDB analytics: millisecond aggregate queries across hundreds of thousands of messages in the TUI, CLI, and MCP server
- Incremental sync: History API picks up only new and changed messages
- Multi-account: archive several Gmail and IMAP accounts in a single database
- Resumable: interrupted syncs resume from the last checkpoint
- Content-addressed attachments: deduplicated by SHA-256
macOS / Linux:
curl -fsSL https://msgvault.io/install.sh | bashWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex"The installer detects your OS and architecture, downloads the latest release from GitHub Releases, verifies the SHA-256 checksum, and installs the binary. You can review the script (bash, PowerShell) before running, or download a release binary directly from GitHub.
To build from source instead (requires Go 1.25+ and a C/C++ compiler for CGO and to statically link DuckDB):
git clone https://github.com/wesm/msgvault.git
cd msgvault
make installConda-Forge:
You can install msgvault from conda-forge using Pixi or Conda:
pixi global install msgvault
conda install -c conda-forge msgvaultPrerequisites: You need a Google Cloud OAuth credential before adding an account. Follow the OAuth Setup Guide to create one (~5 minutes).
msgvault init-db
msgvault add-account you@gmail.com # opens browser for OAuth
msgvault sync-full you@gmail.com --limit 100
msgvault tui| Command | Description |
|---|---|
init-db |
Create the database |
add-account EMAIL |
Authorize a Gmail account (use --headless for servers) or add an IMAP account |
sync-full EMAIL |
Full sync (--limit N, --after/--before for date ranges) |
sync EMAIL |
Sync only new/changed messages |
tui |
Launch the interactive TUI (--account to filter, --local to force local) |
search QUERY |
Search messages (--account to filter, --json for machine output) |
show-message ID |
View full message details (--json for machine output) |
mcp |
Start the MCP server for AI assistant integration |
serve |
Run daemon with scheduled sync and HTTP API for remote TUI |
stats |
Show archive statistics |
list-accounts |
List synced email accounts |
verify EMAIL |
Verify archive integrity against Gmail |
export-eml |
Export a message as .eml |
import-mbox |
Import email from an MBOX export or .zip of MBOX files |
import-emlx |
Import email from an Apple Mail directory tree |
build-cache |
Rebuild the Parquet analytics cache |
update |
Update msgvault to the latest version |
setup |
Interactive first-run configuration wizard |
repair-encoding |
Fix UTF-8 encoding issues |
list-senders / list-domains / list-labels |
Explore metadata |
See the CLI Reference for full details.
Import email from providers that offer MBOX exports or from a local Apple Mail data directory:
msgvault init-db
msgvault import-mbox you@example.com /path/to/export.mbox
msgvault import-mbox you@example.com /path/to/export.zip # zip of MBOX files
msgvault import-emlx # auto-discover Apple Mail accounts
msgvault import-emlx you@example.com ~/Library/Mail/V10 # explicit pathAll data lives in ~/.msgvault/ by default (override with MSGVAULT_HOME).
# ~/.msgvault/config.toml
[oauth]
client_secrets = "/path/to/client_secret.json"
[sync]
rate_limit_qps = 5See the Configuration Guide for all options.
msgvault includes an MCP server that lets AI assistants search, analyze, and read your archived messages. Connect it to Claude Desktop or any MCP-capable agent and query your full message history conversationally. See the MCP documentation for setup instructions.
Run msgvault as a long-running daemon for scheduled syncs and remote access:
msgvault serveConfigure scheduled syncs in config.toml:
[[accounts]]
email = "you@gmail.com"
schedule = "0 2 * * *" # 2am daily (cron)
enabled = true
[server]
api_port = 8080
bind_addr = "0.0.0.0"
api_key = "your-secret-key"The TUI can connect to a remote server by configuring [remote].url. Use --local to force local database when remote is configured. See docs/api.md for the HTTP API reference.
- Setup Guide: OAuth, first sync, headless servers
- Searching: query syntax and operators
- Interactive TUI: keybindings, views, deletion staging
- CLI Reference: all commands and flags
- Multi-Account: managing multiple Gmail accounts
- Configuration: config file and environment variables
- Architecture: SQLite, Parquet, and attachment storage
- MCP Server: AI assistant integration
- Troubleshooting: common issues and fixes
- Development: contributing, testing, building
Join the msgvault Discord to ask questions, share feedback, report issues, and connect with other users.
git clone https://github.com/wesm/msgvault.git
cd msgvault
make test # run tests
make lint # run linter
make install # build and installMIT. See LICENSE for details.