Content
# mailctx
[](https://github.com/hannokuegler/mailctx/actions)
[](https://www.python.org/downloads/release/python-3100/)
[](https://opensource.org/licenses/MIT)
**Give your agent your inbox — clean, token-cheap Markdown from any IMAP account, plus an MCP server so Claude Desktop can read and draft your mail.**
LLMs drown in the `<style>` tags, deeply nested quotes, and tracking pixels of raw email. `mailctx` is a provider-agnostic IMAP engine that strips the garbage and emits bounded, token-optimized Markdown ready for context windows.
### The Token Economy (Actual `mailctx demo` output)
```text
mailctx Token Economy Demo
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ File ┃ Orig Size ┃ Clean Size ┃ Tokens (est.) ┃ Reduction ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ ugly_html.eml │ 1208 c │ 151 c │ ~37 t │ -88% │
│ with_attachment.eml │ 761 c │ 33 c │ ~8 t │ -96% │
│ rich_html.eml │ 2065 c │ 567 c │ ~141 t │ -73% │
│ quoted_thread.eml │ 519 c │ 76 c │ ~19 t │ -85% │
│ tracking.eml │ 659 c │ 17 c │ ~4 t │ -97% │
│ umlaut.eml │ 445 c │ 153 c │ ~38 t │ -66% │
│ plain_text.eml │ 346 c │ 143 c │ ~35 t │ -59% │
│ long_thread.eml │ 1398 c │ 28 c │ ~7 t │ -98% │
└─────────────────────┴───────────┴────────────┴───────────────┴───────────┘
```
*(Run `mailctx demo` to see this exact output on the bundled corpus.)*
## Quickstart
```bash
# 1. Install (with MCP support)
pip install "mailctx[mcp]"
# 2. See the token savings on bundled samples
mailctx demo
# 3. Connect your inbox
mailctx init
```
## The Missing IMAP MCP Server for Claude Desktop
Connect `mailctx` via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) and your agent can answer *"what did I miss this week?"*, *"find the invoice from Flixbus"*, or *"draft a reply to my landlord"*.
**Safety Boundary:** By design, `mailctx` can read mail and it can draft replies (appending to your Drafts folder). **It can never send mail or delete mail.** You always retain final send authority in your standard email client. For an agent touching your inbox, this constraint *is* the feature.
Add this snippet to your `claude_desktop_config.json` (or run `mailctx mcp --print-config`):
```json
{
"mcpServers": {
"mailctx": {
"command": "mailctx",
"args": ["mcp"],
"env": {
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
## Why not just use...
| | mailctx | roll your own `imaplib` | himalaya | mail2md scripts |
|---|---|---|---|---|
| **Token-optimized output for LLMs** | ✅ 85–97% reduction | ❌ | ❌ | partly |
| **MCP server included** | ✅ | ❌ | ❌ | ❌ |
| **Survives VPN/travel disconnects** | ✅ typed retry | ❌ | partly | ❌ |
| **Multi-account isolation** | ✅ | ❌ | ✅ | ❌ |
| **Cannot send (safety boundary)** | ✅ by design | — | ❌ sends | — |
*Note: If you want a full terminal email client to read your own mail, use [himalaya](https://github.com/pimalaya/himalaya). If you need total control over raw MIME parts for a non-LLM pipeline, rolling your own `imaplib` wrapper might be better. `mailctx` is purpose-built for AI agents.*
## Built for Reality
Agents break when connections drop. `mailctx` is engineered to survive production:
- **Typed transient-vs-auth error handling**: Born from real Gmail EOF drops on travel WLAN/VPNs. Uses 3-retry backoff with a fresh connection each attempt.
- **Per-account isolation**: One broken account (e.g., expired app password) never blocks the others.
- **Watermark integrity**: The read pointer (`mailctx stream`) advances only on success, so mail is never silently skipped during processing failures.
- **Autodraft safety model**: Dry-run by default (requires `--write`), capped per run, idempotent, every draft explicitly marked, and structurally incapable of sending.
## See it in Action
*(To regenerate the demo recording locally, run `scripts/record_demo.sh`)*
## Development
Run `mailctx doctor` to verify your environment. For contribution guidelines and "good first issues", see [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT
