mail-archive

Per-project Outlook PST / live-folder mail archive with incremental sync. Designed to be driven either from a plain CLI or from any AI assistant (Claude, Gemini, ChatGPT, local LLMs) via an MCP server or by piping JSON output.

Status: pre-alpha. APIs and config schema will change.

What it does

Given one or more Outlook folders (or PST files) already split by project, mail-archive incrementally ingests new mail into a per-project local archive stored as JSON. Downstream tools (an AI, a script, a MCP client) can then answer questions about that history without re-parsing Outlook every time.

Requirements

• Windows + Outlook desktop (for the live-folder / COM source)
• Python 3.11+
• pip install mail-archive[outlook] for the pywin32 dependency

Only pywin32 is required for basic use; [mcp] adds AI-client support.

Quick start

# 1. Install
pip install "mail-archive[outlook]"

# 2. Create a config file (edit projects afterwards)
mail-archive init

# 3. Ingest the first batch (Outlook must be running)
mail-archive ingest --project "ProjectA"

# 4. Later, sync everything incrementally
mail-archive update-all

Config

~/.mail-archive/config.toml:

storage_dir = "~/.mail-archive/storage"

[[project]]
name = "ProjectA"
source = "outlook-folder"
folder = "Inbox/ProjectA"
auto_update = true

[[project]]
name = "ProjectB"
source = "outlook-folder"
folder = "Inbox/ProjectB"

Using it from an AI assistant (MCP)

mail-archive ships a Model Context Protocol server so any MCP-capable client — Claude Desktop, Cursor, Cline, Zed, Continue, and others — can query the archive directly.

pip install "mail-archive[outlook,mcp]"

Then point your client at the mail-archive-mcp command. Example config for Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mail-archive": {
      "command": "mail-archive-mcp",
      "args": ["--config", "C:/Users/you/.mail-archive/config.toml"]
    }
  }
}

Cursor / Cline / Zed use the same shape — look for their mcpServers JSON block and drop in the same command + args.

The server exposes four tools: list_projects, query_emails, update_project, and update_all. Once loaded, you can ask the AI things like "show me the three most recent emails about topic X in ProjectA" and it will pick the right tool and arguments on its own.

Design

• Storage layout is stable: <storage_dir>/_index.json + <storage_dir>/<project>/emails.jsonl.
• Every CLI subcommand is pure Python and prints JSON on stdout (except update-all, which is quiet by default).
• The MCP server is a thin wrapper over the same library functions — no subprocesses, no duplicated logic.
• Sources are pluggable: implement one function in mail_archive.sources and dispatch to it from fetch_for_project.