Mailctx

CI Python 3.10+ License: 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)

                         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

# 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) 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):

{
  "mcpServers": {
    "mailctx": {
      "command": "mailctx",
      "args": ["mcp"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Why not just use...

Note: If you want a full terminal email client to read your own mail, use 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.

License

MIT