msgvault

module

v0.7.0 Latest Latest Go to latest Published: Feb 9, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/wesm/msgvault

Links

Open Source Insights

README ¶

msgvault

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.

Why msgvault?

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, with WhatsApp and other messaging platforms planned.

Features

Full Gmail backup: raw MIME, attachments, labels, and metadata
Interactive TUI: drill-down analytics over your entire message history, powered by DuckDB over Parquet
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 accounts in a single database
Resumable: interrupted syncs resume from the last checkpoint
Content-addressed attachments: deduplicated by SHA-256

Installation

macOS / Linux:

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

Windows (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 install

Quick Start

Prerequisites: 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

Commands

Command	Description
`init-db`	Create the database
`add-account EMAIL`	Authorize a Gmail account (use `--headless` for servers)
`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)
`search QUERY`	Search messages (`--json` for machine output)
`mcp`	Start the MCP server for AI assistant integration
`stats`	Show archive statistics
`verify EMAIL`	Verify archive integrity against Gmail
`export-eml`	Export a message as `.eml`
`build-cache`	Rebuild the Parquet analytics cache
`repair-encoding`	Fix UTF-8 encoding issues
`list-senders` / `list-domains` / `list-labels`	Explore metadata

See the CLI Reference for full details.

Configuration

All 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 = 5

See the Configuration Guide for all options.

MCP Server

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.

Documentation

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

Community

Join the msgvault Discord to ask questions, share feedback, report issues, and connect with other users.

Development

git clone https://github.com/wesm/msgvault.git
cd msgvault
make test           # run tests
make lint           # run linter
make install        # build and install

License

MIT. See LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
msgvault command
msgvault/cmd
internal
api Package api provides the HTTP API server for msgvault.	Package api provides the HTTP API server for msgvault.
config Package config handles loading and managing msgvault configuration.	Package config handles loading and managing msgvault configuration.
deletion Package deletion provides safe, staged email deletion from Gmail.	Package deletion provides safe, staged email deletion from Gmail.
export Package export handles file export operations such as creating zip archives of email attachments.	Package export handles file export operations such as creating zip archives of email attachments.
fileutil Package fileutil provides cross-platform secure file operations.	Package fileutil provides cross-platform secure file operations.
gmail Package gmail provides a Gmail API client with rate limiting and retry logic.	Package gmail provides a Gmail API client with rate limiting and retry logic.
mcp
mime Package mime provides MIME message parsing using enmime.	Package mime provides MIME message parsing using enmime.
oauth Package oauth provides OAuth2 authentication flows for Gmail.	Package oauth provides OAuth2 authentication flows for Gmail.
query Package query provides a reusable query layer for msgvault.	Package query provides a reusable query layer for msgvault.
query/querytest Package querytest provides shared test doubles for the query.Engine interface.	Package querytest provides shared test doubles for the query.Engine interface.
scheduler Package scheduler provides cron-based scheduling for automated email sync.	Package scheduler provides cron-based scheduling for automated email sync.
search Package search provides Gmail-like search query parsing.	Package search provides Gmail-like search query parsing.
store Package store provides database access for msgvault.	Package store provides database access for msgvault.
sync Package sync provides Gmail synchronization workflows.	Package sync provides Gmail synchronization workflows.
testutil Package testutil provides test helpers for msgvault tests.	Package testutil provides test helpers for msgvault tests.
testutil/dbtest Package dbtest provides shared database test helpers for seeding and querying test databases.	Package dbtest provides shared database test helpers for seeding and querying test databases.
testutil/email Package email provides test helpers for constructing raw RFC 2822 email messages.	Package email provides test helpers for constructing raw RFC 2822 email messages.
testutil/ptr Package ptr provides generic pointer helpers for tests.	Package ptr provides generic pointer helpers for tests.
testutil/storetest Package storetest provides a StoreFixture and helpers for tests that exercise the Store layer through its public API.	Package storetest provides a StoreFixture and helpers for tests that exercise the Store layer through its public API.
testutil/tbmock Package tbmock provides a mock testing.TB for verifying fail-fast behavior.	Package tbmock provides a mock testing.TB for verifying fail-fast behavior.
textutil Package textutil provides text manipulation and encoding utilities.	Package textutil provides text manipulation and encoding utilities.
tui Package tui provides a terminal user interface for msgvault.	Package tui provides a terminal user interface for msgvault.
update
scripts
mimeshootout command MIME Library Shootout	MIME Library Shootout