Mailctx

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 ` 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...

| | 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. 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hannokuegler
• Source: hannokuegler/mailctx
• License: MIT

Install and usage instructions live in the source repository linked above.