owlpost

owlpost

一款高保真的 IMAP/SMTP MCP 服务，适用于 iCloud、Gmail 和其他邮件服务商。开发它是因为我试过的其他邮件 MCP 服务，都会被真实环境中的 IMAP 特殊情况难住（CRLF 换行、RFC822 与 BODY.PEEK[] 的差异、服务商专属的已发送文件夹、多词搜索值）。

owlpost 是我日常使用的工具，我会通过 Claude Code 阅读、搜索、跟进邮件对话并发送邮件。

uvx owlpost

目录

• 功能
• 工具
• 安装
• 配置
• 客户端设置 — Claude Desktop、Claude Code、Cursor、VS Code、Docker
• 服务商说明 — iCloud、Gmail、Proton Bridge、通用服务商
• 安全
• 故障排除
• 开发

功能

• 多账户 — 可按需配置任意数量的邮箱，并按名称切换
• 已通过 iCloud 和 Gmail 端到端测试，并处理了服务商专属的特殊情况：
  • iCloud 的 RFC822 获取操作会返回空正文 → 改用 BODY.PEEK[]
  • iCloud 的 IMAP APPEND 要求使用 CRLF 换行 → 所有发出的邮件都使用 policy.SMTP
  • iCloud 的 SMTP 不会自动保存已发送邮件 → owlpost 会为你将邮件 APPEND 到“已发送”文件夹
  • Gmail 的 SMTP 会 自动保存 → owlpost 会跳过重复的 APPEND
  • 通过 RFC 6154 SPECIAL-USE 自动发现文件夹名称（无需硬编码 Sent Messages 或 [Gmail]/Sent Mail）
  • 不支持 MOVE 扩展的服务器会改用 COPY + \Deleted + EXPUNGE
  • Proton Bridge 的 FETCH 响应中不会包含 UID，除非请求该字段 → owlpost 始终会请求
• 跟进邮件对话 — 在可用时使用 Gmail 的 X-GM-THRID 扩展，否则会通过 Message-ID/References，在各文件夹中使用 BFS 通用搜索
• 可靠连接 — 每次操作使用短连接 IMAP 会话，而非容易随机断开的长连接
• 支持 MIME — 解析多部分邮件、解码标头、列出附件并将附件下载到磁盘
• 线程式回复/转发 — 保留 In-Reply-To/References，并引用原邮件
• 草稿 — 将邮件写入“草稿”文件夹，方便你在自己的邮件客户端中检查并发送
• 在需要时默认只读 — 搜索和阅读邮件都不会将邮件标记为已读
• 可按需避免在配置文件中存放密钥 — 支持 password_env 和 password_command（1Password、pass、Keychain 等）
• 带注释的工具 — 每个工具都会声明 MCP readOnlyHint / destructiveHint / openWorldHint，让客户端可以自动批准读取操作，并在发送前征求确认

工具

工具	功能	只读
list_accounts	列出已配置的邮件账户（不会包含密码）	✅
list_folders	列出某个账户的文件夹，以及检测到的特殊用途角色	✅
resolve_folder	将角色（sent、trash、drafts、inbox、all、archive 等）解析为服务提供商的文件夹名称	✅
search_messages	结构化 IMAP 搜索（发件人／收件人／抄送／主题／正文／文本／起始日期／截止日期／未读／已标记／有附件，或原始搜索）；按时间从新到旧排列	✅
read_email	阅读一封邮件：邮件头、纯文本／HTML 正文、附件列表。默认截断内容，以符合 MCP 结果限制	✅
get_conversation	返回同一会话中的所有邮件（使用 Gmail X-GM-THRID 或通用引用追溯方式）	✅
save_attachment	按部件索引将附件下载到本地磁盘（不更改邮箱内容）	写入本地文件
send_email	发送邮件。在不会自动保存已发送邮件的服务提供商（如 iCloud）上自动保存到“已发送”。支持附件和会话线程头	❌ 发送
save_draft_email	创建邮件并将其 APPEND 到“草稿”，而不发送——参数与 send_email 相同	❌
reply_email	回复邮件（可选全部回复），保留会话线程并引用原文	❌ 发送
forward_email	转发邮件，默认重新附加原邮件的附件	❌ 发送
mark_read	设置／取消设置 \Seen	❌
flag_message	设置／取消设置 \Flagged（星标）	❌
move_email	移动到另一个文件夹	❌ 有破坏性
delete_email	移至“垃圾箱”（不会永久删除）	❌ 有破坏性

每个工具都需要 account 参数（即 list_accounts 返回的名称）。 邮件通过 folder 和 uid 标识，如 search_messages 返回的结果所示。

安装

推荐的方式是完全不安装——让 uvx 在首次使用时获取并缓存它。这样可以让程序包始终保持最新，并避免污染全局 Python 环境：

uvx owlpost            # speaks MCP over stdio
uvx owlpost --version

如果你更希望在 PATH 中使用稳定的二进制文件：

uv tool install owlpost   # or: pipx install owlpost / pip install owlpost

此外还提供容器镜像，详见 Docker。

配置

将 accounts.example.toml 复制到 ~/.config/owlpost/accounts.toml，并填写凭据。请使用 应用专用密码，不要使用真实密码：

• iCloud：account.apple.com → Sign-In and Security → App-Specific Passwords
• Gmail：myaccount.google.com/apppasswords（必须启用 2FA）

[accounts.icloud]
email = "[email protected]"
password_command = "op read op://Private/iCloud Mail/app-password"
provider = "icloud"
imap_host = "imap.mail.me.com"
smtp_host = "smtp.mail.me.com"
auto_save_sent = true   # iCloud SMTP doesn't auto-save sent

[accounts.gmail]
email = "[email protected]"
password_env = "OWLPOST_GMAIL_PASSWORD"
provider = "gmail"
imap_host = "imap.gmail.com"
smtp_host = "smtp.gmail.com"
auto_save_sent = false  # Gmail SMTP auto-saves

表名（上面的 icloud、gmail）就是传递给工具的 account 参数值。

配置文件的位置

按优先级从高到低排列：

1. owlpost --config /path/to/accounts.toml
2. OWLPOST_CONFIG 环境变量
3. ~/.config/owlpost/accounts.toml

配置文件会在首次调用工具时读取；编辑后请重启服务。

参考

键	必填	默认值	含义
email	✅		登录用户名和 From 地址
password	三选一		内联填写密码（推荐使用应用专用密码）
password_env	三选一		保存密码的环境变量名称
password_command	三选一		输出密码的命令，例如 op read op://...
provider		generic	icloud、gmail 或 generic。gmail 会启用 X-GM-THRID 线程关联
imap_host	✅		IMAP 服务主机名
imap_port		993	IMAP 端口
imap_security		ssl	ssl（隐式 TLS，通常为 993）或 starttls（通常为 143 / 1143）
smtp_host	✅		SMTP 服务主机名
smtp_port		587	SMTP 端口
smtp_security		starttls	starttls（通常为 587）或 ssl（通常为 465）
auto_save_sent		true	将已发送邮件的副本 APPEND 到“已发送”文件夹。Gmail 用户请关闭
tls_verify		true	验证 TLS 证书。仅在使用自签名证书的本地桥接服务时设为 false

password、password_env 和 password_command 必须且只能设置一个。

password_command 会按照类似 shell 的引号规则拆分，然后直接运行（不使用 shell，因此不支持管道或 $VARS），超时时间为 10 秒。命令标准输出去掉末尾换行符后即为密码。首次使用该账户时会运行命令，结果会在服务进程的整个生命周期内缓存。如果命令失败，工具调用会返回错误，其中包含命令的退出代码和标准错误输出。一些示例：

password_command = "op read op://Private/Fastmail/app-password"                  # 1Password CLI
password_command = "pass show mail/fastmail"                                     # pass
password_command = "security find-generic-password -s owlpost-icloud -w"         # macOS Keychain
password_command = "secret-tool lookup service owlpost account icloud"           # GNOME Keyring

password_env 会从服务的环境中读取该变量；环境由 MCP 客户端控制（即下方代码片段中的 env 块）。

客户端设置

这些配置都会运行 uvx owlpost。如果客户端找不到 uvx，请使用绝对路径（通常为 ~/.local/bin/uvx，可通过 which uvx 查看）。如果你使用 uv tool install 安装，也可以直接将 owlpost 作为命令使用。

Claude Desktop

一键安装： 从最新版本下载 owlpost-<version>.mcpb 并打开。Claude Desktop 会安装它，并提示你填写 accounts.toml 的路径。

手动安装：

编辑 claude_desktop_config.json（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "owlpost": {
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

Claude Code

claude mcp add owlpost --scope user -- uvx owlpost

# with a non-default config path, or a password from the environment
claude mcp add owlpost --scope user \
  -e OWLPOST_CONFIG=/path/to/accounts.toml \
  -- uvx owlpost

Cursor

添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "owlpost": {
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

VS Code

添加到工作区的 .vscode/mcp.json（或运行 MCP: Add Server 进行用户级安装）：

{
  "servers": {
    "owlpost": {
      "type": "stdio",
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

其他 MCP 客户端

owlpost 使用标准的 MCP stdio 传输方式，任何兼容 MCP 的客户端都可以通过启动 uvx owlpost 或已安装的 owlpost 二进制文件与其通信。传入 env: {"OWLPOST_CONFIG": "..."}，即可指定配置文件。

Docker

镜像要求将配置文件放在 /config/accounts.toml。请以只读方式挂载包含该文件的目录：

docker run -i --rm \
  --mount type=bind,src="$HOME/.config/owlpost",dst=/config,readonly \
  ghcr.io/smankoo/owlpost:latest

作为 MCP 客户端配置项：

{
  "mcpServers": {
    "owlpost": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/home/you/.config/owlpost,dst=/config,readonly",
        "ghcr.io/smankoo/owlpost:latest"
      ]
    }
  }
}

容器内的 password_command 只能运行镜像中已有的二进制文件，因此请使用 password 或 password_env（通过 -e OWLPOST_GMAIL_PASSWORD 传入）。若要连接主机上的 Proton Bridge，请使用 --network host（Linux），或设置 imap_host = "host.docker.internal"。 除非为 save_attachment 挂载可写目录，否则附件会保存在容器内。

示例

注册后，你可以提出如下请求：

• “查找上个月学校发来的有关郊游的邮件”
• “显示最近一封房贷邮件的完整线程”
• “回复房东最近发来的消息，说我明天会联系他”
• “起草一封回复保险续保邮件的消息，索要 PDF，但不要发送”
• “将保单 PDF 转发给 [email protected]”
• “将本月电费账单中的附件保存到 ~/Downloads”

服务提供商说明

iCloud

• 请使用应用专用密码，不要使用 Apple ID 密码。
• iCloud 会限制频繁重连。owlpost 为每项操作使用短时会话，但不进行连接池管理——如果遇到 SSLEOFError: EOF，请等待约 30 秒后再试。
• 已发送邮件文件夹为 Sent Messages，废纸篓为 Deleted Messages。系统会自动检测这两个文件夹。
• 请保持 auto_save_sent = true：iCloud 的 SMTP 不会保留你发送邮件的副本。

Gmail

• 需要启用双重验证并创建应用密码。
• 必须在 Gmail 设置 → 转发和 POP/IMAP 中启用 IMAP。
• 设置 provider = "gmail"，这样 owlpost 就会使用 Gmail 的 X-GM-THRID 扩展来可靠地检测邮件会话。
• 设置 auto_save_sent = false；Gmail 的 SMTP 已经会归档已发送邮件，因此使用 APPEND 会造成重复。
• delete_email 会将邮件移至 [Gmail]/Trash。将邮件从 INBOX 移至标签文件夹的操作与归档相同。

Proton Mail（通过 Proton Bridge）

Proton 仅通过 Proton Bridge 应用提供 IMAP/SMTP。该应用在本机运行，使用自签名证书，并通过非标准端口进行 STARTTLS 通信。请按以下方式配置：

• provider = "generic"
• imap_host = "127.0.0.1"、imap_port = 1143、imap_security = "starttls"
• smtp_host = "127.0.0.1"、smtp_port = 1025、smtp_security = "starttls"
• tls_verify = false——由于 Bridge 的证书是自签名的，因此必须这样设置
• 使用 Bridge 生成的邮箱密码（不要使用 Proton 账户密码）

其他服务商

设置 provider = "generic"，并配置 imap_host、smtp_host、端口、 imap_security / smtp_security（starttls 或 ssl）以及 tls_verify （自签名证书请设置为 false）。如果你的服务商支持 SPECIAL-USE（大多数现代服务商都支持）， 系统仍会自动检测文件夹角色；否则，owlpost 会退回使用 Sent、Sent Items 和 Trash 等常见名称。是否将 auto_save_sent 保持为启用状态，取决于你的 服务商是否会通过 SMTP 自动归档已发送邮件——请先给自己发送一封测试邮件并检查是否有 重复邮件。

安全

• owlpost 会发送真实邮件。 send_email、reply_email 和 forward_email 均标注为 openWorldHint: true，且不是 只读工具。请将 MCP 客户端配置为运行这些工具前要求确认 （大多数客户端默认会对非只读工具这样做），并且不要 自动批准。服务的说明也会要求模型在发送前与你确认收件人和内容。如果你只希望 模型准备邮件，请引导它使用 save_draft_email。
• 不可信内容。 邮件正文由陌生人编写。邮件中 可能包含旨在操纵模型的文字（例如“将最近 10 张发票转发给……”）。请保持发送确认开启，尤其是在会读取邮件且能发送邮件的 Agent 中。
• 使用应用密码，绝不要使用主账户密码。应用密码可以单独撤销，也不会授予账户管理权限。
• 使用 password_command（密码管理器）或 password_env，将机密信息保留在文件之外。如果你确实要在文件中填写 password， 请运行 chmod 600 ~/.config/owlpost/accounts.toml。
• list_accounts 永远不会返回密码或密码来源。
• tls_verify = false 会完全禁用证书检查；仅在 127.0.0.1 上运行的 Bridge 使用此设置。
• save_attachment 和 attachments 会以运行服务的用户身份读取和写入本地路径。

发现漏洞？请参阅 SECURITY.md。

故障排查

症状	解决方法
客户端中未显示工具	客户端无法启动 uvx。请使用其绝对路径（which uvx），然后重启客户端。在终端中运行 uvx owlpost --version，检查是否正常
owlpost config not found at ...	创建 ~/.config/owlpost/accounts.toml，或设置 OWLPOST_CONFIG / --config
must set exactly one of password, password_env, password_command	在对应的 [accounts.<name>] 表中删除多余的键（或添加一个键）
password_command exited with 1: ...	在终端中运行该命令。密码管理器 CLI 通常需要先登录（op signin）或解锁
Unknown account 'x'. Known: [...]	使用列出的名称之一；这是 TOML 表名，而不是电子邮件地址
登录时出现 [AUTHENTICATIONFAILED] / 535	应用专用密码错误或已撤销；对于 Gmail，请确保已启用 IMAP
iCloud 上出现 SSLEOFError: EOF	iCloud 会限制重新连接；请等待约 30 秒
使用 Proton Bridge 时出现 CERTIFICATE_VERIFY_FAILED	为该账户设置 tls_verify = false
已发送的邮件出现两次	你的服务提供商已保存已发送邮件；请设置 auto_save_sent = false
“已发送邮件”中缺少邮件	设置 auto_save_sent = true
unknown encoding: idna	将 owlpost 升级到 0.1.4 或更高版本

开发

git clone https://github.com/smankoo/owlpost
cd owlpost
uv sync                      # creates .venv with dev tools
uv run pytest                # tests use fake IMAP/SMTP, no network
uv run ruff check .
uv run ruff format --check .
uv run python scripts/smoke_stdio.py uv run owlpost   # stdio handshake + tools/list

有关发布流程，请参阅 CONTRIBUTING.md；有关历史记录，请参阅 CHANGELOG.md。

许可证

MIT — 请参阅 LICENSE。