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