# Mailctx

> 📬 Give your AI agent your inbox. Provider-agnostic IMAP → clean, token-cheap Markdown (60–98% fewer tokens), plus an MCP server so Claude Desktop can search, read and draft your mail. Reads and drafts — never sends.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hannokuegler-mailctx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hannokuegler](https://agentstack.voostack.com/s/hannokuegler)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hannokuegler](https://github.com/hannokuegler)
- **Source:** https://github.com/hannokuegler/mailctx

## Install

```sh
agentstack add mcp-hannokuegler-mailctx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## 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](https://github.com/hannokuegler)
- **Source:** [hannokuegler/mailctx](https://github.com/hannokuegler/mailctx)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hannokuegler-mailctx
- Seller: https://agentstack.voostack.com/s/hannokuegler
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.