{
  "markdown": "# mbox-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server for **local email archives**. Point it at a Google Takeout `.mbox` export or a folder of `.eml` files and ask Claude things like:\n\n- *\"Who did I email most in this archive?\"*\n- *\"Find the message where the landlord mentioned the lease renewal.\"*\n- *\"Summarize my correspondence with bob@example.com from early 2026.\"*\n\n**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.\n\n## Quick start\n\n**Claude Code**\n\n```bash\nclaude mcp add mbox -- npx -y mbox-mcp\n```\n\n**Claude Desktop** — add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mbox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mbox-mcp\"]\n    }\n  }\n}\n```\n\nThen: *\"Open C:\\\\Takeout\\\\Mail\\\\All mail Including Spam and Trash.mbox and tell me about it.\"*\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `open_archive` | Index an .mbox file or .eml directory: message count, date range, top senders |\n| `search_messages` | Search by keyword, sender, subject, date range — plus bounded body-text search |\n| `get_message` | Fully parse one message: decoded body, headers, attachment names/sizes |\n\n## Built for large archives\n\nA Takeout mbox is often multiple gigabytes with 100k+ messages. The design reads the minimum, lazily:\n\n- **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).\n- **Full MIME on demand** — reading a message parses just that message ([postal-mime](https://github.com/postalsys/postal-mime): nested multipart, charsets, quoted-printable/base64). Attachments are listed with names and sizes, never dumped into context.\n- **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.\n- **Staleness-aware cache** — archives are indexed once per process and re-indexed if the file changes.\n\n## Notes and limitations\n\n- 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.\n- Attachment *contents* are never returned or written anywhere.\n- PST/OST and Maildir are out of scope for now.\n\n## Development\n\n```bash\nnpm install\nnpm test                 # offline tests — synthetic archives built in-suite\nnpm run build            # tsc → dist/\nnode scripts/smoke.mjs   # end-to-end: generates an archive, drives the server over stdio\n```\n\nArchitecture: [`src/archive.ts`](src/archive.ts) (streaming indexer, header decoding, envelope filtering) and [`src/reader.ts`](src/reader.ts) (per-message MIME parsing) are pure logic; [`src/index.ts`](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.\n\n## License\n\nMIT\n",
  "bytes": 3263,
  "sha": "16443e561c3c32a0ce1f2016862afeecec8a5269a7323f54a1a946657f424514",
  "repo_slug": "arose26/mbox-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arose26_mbox_mcp_a82919ca/readme"
}