{"_id":"mbox-mcp","_rev":"2-346a4d63f997fa10d848da6968b7d790","name":"mbox-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"mbox-mcp","version":"0.1.0","keywords":["mcp","mcp-server","model-context-protocol","mbox","eml","email","google-takeout","thunderbird","archive","privacy","local","claude"],"author":{"name":"Kole Harvey"},"license":"MIT","_id":"mbox-mcp@0.1.0","maintainers":[{"name":"koleharvey","email":"cinnamonolive@emalupe.com"}],"homepage":"https://github.com/arose26/mbox-mcp#readme","bugs":{"url":"https://github.com/arose26/mbox-mcp/issues"},"bin":{"mbox-mcp":"dist/index.js"},"dist":{"shasum":"0a11bc43d3f2ede758cd0343373224d1630b5de1","tarball":"https://registry.npmjs.org/mbox-mcp/-/mbox-mcp-0.1.0.tgz","fileCount":9,"integrity":"sha512-aA3+qNqy7SZKUFrvxo0z2X0I4CxW8kHVGWTd11iVswP9Xs6mTBqgbS4f1y1Yg+Xj+N8tW9oYxKQKdXcYB842fQ==","signatures":[{"sig":"MEQCIAJa7E/Qx37oWNJ4ysxn27k1NnUKcroELmhlT7y6hgPBAiA76RnaeprHFp5T3eH0eCpmz1mIY1DoqUAblteKz908fA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23520},"type":"module","engines":{"node":">=18"},"gitHead":"f610e29383f62aa0c81c87a6c09d58dfab543876","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"koleharvey","email":"cinnamonolive@emalupe.com"},"repository":{"url":"git+https://github.com/arose26/mbox-mcp.git","type":"git"},"_npmVersion":"11.19.0","description":"MCP server for local email archives — search and read Google Takeout .mbox exports and .eml files entirely on your machine. No OAuth, no IMAP, no cloud.","directories":{},"_nodeVersion":"26.7.0","dependencies":{"zod":"^3.25.0","postal-mime":"^3.0.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mbox-mcp_0.1.0_1786748817159_0.12790646958068508","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"mbox-mcp","version":"0.1.1","mcpName":"io.github.arose26/mbox-mcp","description":"MCP server for local email archives — search and read Google Takeout .mbox exports and .eml files entirely on your machine. No OAuth, no IMAP, no cloud.","type":"module","bin":{"mbox-mcp":"dist/index.js"},"scripts":{"build":"tsc","test":"vitest run","prepublishOnly":"npm run build && npm test"},"keywords":["mcp","mcp-server","model-context-protocol","mbox","eml","email","google-takeout","thunderbird","archive","privacy","local","claude"],"license":"MIT","author":{"name":"Kole Harvey"},"repository":{"type":"git","url":"git+https://github.com/arose26/mbox-mcp.git"},"engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","postal-mime":"^3.0.0","zod":"^3.25.0"},"devDependencies":{"typescript":"^5.7.0","vitest":"^3.0.0","@types/node":"^22.0.0"},"gitHead":"514b64f099f44da5727bc03f2f638020babe948a","_id":"mbox-mcp@0.1.1","bugs":{"url":"https://github.com/arose26/mbox-mcp/issues"},"homepage":"https://github.com/arose26/mbox-mcp#readme","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-piAVDaJo7k/2nNTf+N/0UfhnJl7q7Hqevq0tHw0ylIDvQsdlL3Ft0O/xANkSHOU7ihDcwytX772Aj3h3luWyhg==","shasum":"561f5ebb52b985162c42e20022a2d31632ae28eb","tarball":"https://registry.npmjs.org/mbox-mcp/-/mbox-mcp-0.1.1.tgz","fileCount":9,"unpackedSize":23563,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCMcE79CDTH/ICpktXigEA8mRMGq6FTKot6+QKf51n6XgIhAMrsQnON4jkfpfS9aniBgiRCuUlyfhnfXf4GhazyPEZA"}]},"_npmUser":{"name":"koleharvey","email":"cinnamonolive@emalupe.com"},"directories":{},"maintainers":[{"name":"koleharvey","email":"cinnamonolive@emalupe.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mbox-mcp_0.1.1_1786749386973_0.941955889868241"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T23:06:57.102Z","modified":"2026-08-14T23:16:27.255Z","0.1.0":"2026-08-14T23:06:57.298Z","0.1.1":"2026-08-14T23:16:27.117Z"},"bugs":{"url":"https://github.com/arose26/mbox-mcp/issues"},"author":{"name":"Kole Harvey"},"license":"MIT","homepage":"https://github.com/arose26/mbox-mcp#readme","keywords":["mcp","mcp-server","model-context-protocol","mbox","eml","email","google-takeout","thunderbird","archive","privacy","local","claude"],"repository":{"type":"git","url":"git+https://github.com/arose26/mbox-mcp.git"},"description":"MCP server for local email archives — search and read Google Takeout .mbox exports and .eml files entirely on your machine. No OAuth, no IMAP, no cloud.","maintainers":[{"name":"koleharvey","email":"cinnamonolive@emalupe.com"}],"readme":"# 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","readmeFilename":"README.md"}