内容
# mailctx
[](https://github.com/hannokuegler/mailctx/actions)
[](https://www.python.org/downloads/release/python-3100/)
[](https://opensource.org/licenses/MIT)
**将您的收件箱交给您的代理 — 清洁、节省令牌的 Markdown，来自任何 IMAP 账户，以及一个 MCP 服务器，让 Claude Desktop 可以读取和草拟您的邮件。**
大型语言模型（LLMs）在原始电子邮件的 `<style>` 标签、深度嵌套的引用和跟踪像素中溺亡。`mailctx` 是一个与提供商无关的 IMAP 引擎，它剥去垃圾并发出适用于上下文窗口的、令牌优化的 Markdown。
### 代币经济（实际的 `mailctx demo` 输出）
```text
mailctx 代币经济演示
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ 文件 ┃ 原始大小 ┃ 清洁大小 ┃ 令牌（估计） ┃ 减少 ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ ugly_html.eml │ 1208 字节 │ 151 字节 │ ~37 令牌 │ -88% │
│ with_attachment.eml │ 761 字节 │ 33 字节 │ ~8 令牌 │ -96% │
│ rich_html.eml │ 2065 字节 │ 567 字节 │ ~141 令牌 │ -73% │
│ quoted_thread.eml │ 519 字节 │ 76 字节 │ ~19 令牌 │ -85% │
│ tracking.eml │ 659 字节 │ 17 字节 │ ~4 令牌 │ -97% │
│ umlaut.eml │ 445 字节 │ 153 字节 │ ~38 令牌 │ -66% │
│ plain_text.eml │ 346 字节 │ 143 字节 │ ~35 令牌 │ -59% │
│ long_thread.eml │ 1398 字节 │ 28 字节 │ ~7 令牌 │ -98% │
└─────────────────────┴───────────┴────────────┴───────────────┴───────────┘
```
*（运行 `mailctx demo` 以查看此确切输出在捆绑的语料库上。）*
## 快速入门
```bash
# 1. 安装（带有 MCP 支持）
pip install "mailctx[mcp]"
# 2. 在捆绑的样本上查看令牌节省
mailctx demo
# 3. 连接您的收件箱
mailctx init
```
## 缺失的 IMAP MCP 服务器，适用于 Claude Desktop
通过 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 连接 `mailctx`，您的代理可以回答 *“我这周错过了什么？”*、*“找到来自 Flixbus 的发票”* 或 *“草拟给房东的回复”*。
**安全边界：** 按设计，`mailctx` 可以读取邮件并且可以草拟回复（追加到您的草稿文件夹）。**它永远不能发送邮件或删除邮件。** 您始终在标准电子邮件客户端中保留最终发送权限。对于触及您的收件箱的代理，此约束 *就是* 功能。
将以下代码片段添加到您的 `claude_desktop_config.json`（或运行 `mailctx mcp --print-config`）：
```json
{
"mcpServers": {
"mailctx": {
"command": "mailctx",
"args": ["mcp"],
"env": {
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
## 为什么不直接使用……
| | mailctx | 自己编写 `imaplib` | himalaya | mail2md 脚本 |
|---|---|---|---|---|
| **针对 LLMs 的令牌优化输出** | ✅ 85–97% 减少 | ❌ | ❌ | 部分 |
| **包含 MCP 服务器** | ✅ | ❌ | ❌ | ❌ |
| **在 VPN/旅行断开连接中存活** | ✅ 类型重试 | ❌ | 部分 | ❌ |
| **多账户隔离** | ✅ | ❌ | ✅ | ❌ |
| **无法发送（安全边界）** | ✅ 按设计 | — | ❌ 发送 | — |
*注意：如果您想要一个完整的终端电子邮件客户端来阅读您自己的邮件，请使用 [himalaya](https://github.com/pimalaya/himalaya)。如果您需要对原始 MIME 部分进行完全控制以用于非 LLM 流水线，自己编写 `imaplib` 包装器可能更好。`mailctx` 是专门为 AI 代理构建的。*
## 面向现实世界
代理在连接断开时就会崩溃。`mailctx` 被设计为能够在生产环境中存活：
- **类型化瞬时错误与身份验证错误处理**：源自实际的 Gmail 在旅行 WLAN/VPN 上出现 EOF 丢弃。 使用 3 次重试回退，并为每次尝试建立新的连接。
- **每账户隔离**：一个损坏的账户（例如，过期应用密码）永远不会阻塞其他账户。
- **水位标记完整性**：读取指针（`mailctx stream`）仅在成功时才会前进，因此在处理失败期间邮件永远不会被静默跳过。
- **自动草拟安全模型**：默认干运行（需要 `--write`），每运行限额，幂等，每个草拟都明确标记，并且在结构上无法发送。
## 实际演示
*（要本地重新生成演示录制，请运行 `scripts/record_demo.sh`）*
## 开发
运行 `mailctx doctor` 以验证您的环境。有关贡献指南和“好的第一个问题”，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT
