io.github.arose26/mbox-mcp

mbox-mcp

An MCP server for local email archives. Point it at a Google Takeout .mbox export or a folder of .eml files and ask Claude things like:

• "Who did I email most in this archive?"
• "Find the message where the landlord mentioned the lease renewal."
• "Summarize my correspondence with bob@example.com from early 2026."

Everything stays on your machine. No OAuth, no app passwords, no IMAP connection, no cloud. Every other email MCP server connects to a live account — this one reads the archive files you already have, which is exactly what you want for the 15 years of Gmail sitting in a Takeout export.

Quick start

Claude Code

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

Claude Desktop — add to claude_desktop_config.json:

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

Then: "Open C:\\Takeout\\Mail\\All mail Including Spam and Trash.mbox and tell me about it."

Tools

Built for large archives

A Takeout mbox is often multiple gigabytes with 100k+ messages. The design reads the minimum, lazily:

• Streaming index — one pass in 8 MiB chunks, recording byte offsets; only the current message's first 16 KiB is ever held for envelope parsing (sender, subject, date, RFC 2047 decoding).
• Full MIME on demand — reading a message parses just that message (postal-mime: nested multipart, charsets, quoted-printable/base64). Attachments are listed with names and sizes, never dumped into context.
• Honest body search — body_query only full-parses messages that already match your envelope filters, stops at a scan cap, and reports how many it scanned, so the model knows to narrow by sender or date first.
• Staleness-aware cache — archives are indexed once per process and re-indexed if the file changes.

Notes and limitations

• mbox variants: Takeout and Thunderbird produce mboxrd (body From lines are quoted as >From), which splits cleanly. Plain mboxo archives with unquoted body From lines can over-split.
• Attachment contents are never returned or written anywhere.
• PST/OST and Maildir are out of scope for now.

Development

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

Architecture: src/archive.ts (streaming indexer, header decoding, envelope filtering) and src/reader.ts (per-message MIME parsing) are pure logic; src/index.ts is the MCP wiring. The test suite includes a chunk-seam property test: indexing with pathological 17-byte chunks must produce an identical index to whole-file reads.

License

MIT