pylos-mcp

pylos-mcp

邮件客户端会显示邮件内容。pylos-mcp 会告诉你的助手邮件隐藏了什么。

适用于 Gmail、Outlook 和 Microsoft 365、iCloud 及任何 IMAP 邮箱的邮件 MCP 服务，旨在让每封邮件都以数据而非指令的形式传递给你的助手。

任何人都可以往你的收件箱里写入文本；AI 助手读取收件箱后，他们也就能把文本呈现在助手面前。pylos-mcp 让 Claude 或任何 MCP 客户端搜索、读取和起草邮件，同时将每封邮件都视为来自陌生人的输入，并在助手采取行动前指出邮件隐藏的内容。

每封邮件都会被标记为数据，并附带 Warnings 行，提示看起来可疑的内容，例如隐藏文本、针对 AI 的短语、易混淆字母或 DMARC 检查失败。默认情况下，助手可以读取和起草邮件。移动、发送和删除功能默认关闭，只有在你启用后才可使用；启用发送后，邮件也只能发送给你列出的地址，而且任何地方都不会出现 bcc。它在你的设备上运行，支持 Gmail、Outlook 和 Microsoft 365、iCloud、Yahoo、GMX、Fastmail、mailbox.org、Posteo、通过 Bridge 使用 Proton，或你自己的服务端。

pylos-mcp 会连接你的邮件服务商；使用 Outlook 时，还会连接 Microsoft 的登录服务。助手读取的内容会发送给你的 AI 客户端，并经由它传给你使用的模型服务商，就像你向助手展示其他内容时一样。你请求获取的附件会保存到 Downloads 文件夹。

致命三要素

Simon Willison 将其称为致命三要素：AI Agent 可以访问私人数据、接触不可信内容，并且能够向外部通信。读取你邮件的助手天生就具备前两项，因为你的收件箱是私密的，而且任何人都能给你发邮件。要窃取它读取的内容，还需要第三项：将内容发送到别处的途径。

发送功能默认关闭。草稿会留在“草稿”文件夹中，直到你亲自发送；即使启用发送功能，也必须设置收件人允许列表。设置 SEND_CONFIRM=true 后，每封邮件也会在对话框中显示给你，只有你确认后才会发出。没有任何工具会附加你磁盘上的文件或添加转发规则。

第三项仍可能来自同一客户端中的其他工具，例如获取网页或运行 shell 命令的工具。邮件中的图像标记会被中和，但模型仍可以自行编写图像链接，加载图像的客户端会获取该链接。让助手读取邮件时，不要在同一对话中使用可访问互联网的工具。

隔离措施可以降低提示词注入风险，但无法彻底消除风险。模型仍会读取陌生人编写的文本，因此在据此采取行动前，请检查助手告诉你的邮件内容。

快速开始

pylos-mcp 适用于任何可运行本地 MCP 服务的客户端。它通过 npx 在本地运行，并且需要 Node.js 22 或更高版本。以下每种配置都使用示例值，请将地址和密码替换为你自己的值。请使用应用专用密码，而不是账户的常规密码；Outlook 则完全不需要密码。提供商设置说明了如何获取应用专用密码。

Claude Desktop。 下载 pylos-mcp.mcpb，打开它，然后填写 Desktop 显示的表单。

Claude Code。 --scope user 会让它在每个项目中都可用。EMAIL_PASSWORD_CMD 可避免密码出现在 shell 历史记录和 Claude 配置中：它会运行一条输出密码的命令，此处使用的是 macOS 钥匙串查询命令。请先使用 security add-generic-password -s pylos-mcp -a [email protected] -w 将密码存入钥匙串；系统会提示你输入密码。

claude mcp add pylos-mcp --scope user -e PROVIDER=gmail -e [email protected] \
  -e EMAIL_PASSWORD_CMD="security find-generic-password -s pylos-mcp -w" -- npx -y pylos-mcp

Cursor 和 VS Code。 使用上方的按钮，然后在生成的配置中填入你自己的值。

{
  "mcpServers": {
    "pylos-mcp": {
      "command": "npx",
      "args": ["-y", "pylos-mcp"],
      "env": {
        "PROVIDER": "gmail",
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASSWORD": "your-app-password"
      }
    }
  }
}

{
  "servers": {
    "pylos-mcp": {
      "command": "npx",
      "args": ["-y", "pylos-mcp"],
      "env": {
        "PROVIDER": "gmail",
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASSWORD": "your-app-password"
      }
    }
  }
}

Outlook 和 Microsoft 365 使用 PROVIDER=outlook，完全不需要密码，因此请从条目中删除 EMAIL_PASSWORD，否则服务会拒绝启动。助手首次读取邮件时，浏览器会打开 Microsoft 登录页面。

每次更改后，都请彻底重启客户端，因为工具只会在启动时注册，而且仅关闭再重新开启服务并不总是足够。然后让助手列出你的邮件文件夹。若能看到文件夹列表，就说明配置成功。

如果 Claude Desktop 扩展显示“Server disconnected”，请查看 Desktop 的 main.log。在 macOS 上，日志位于 ~/Library/Logs/Claude；在 Windows 上，位于 %APPDATA%\Claude\logs。相关行以 pylos-mcp: 开头。

功能

每项功能都是一个独立开关，开启一项不会影响其他项。读取功能始终开启，草稿功能默认开启，其余功能在你将其列入 CAPABILITIES 之前都保持关闭。关闭的层级对应的工具会完全从工具列表中移除，因此模型不会知道它们的存在。

可以通过列表启用更多功能，例如 CAPABILITIES=drafts,manage,delete。将邮件移入垃圾箱也属于删除，因此除非同时启用了 delete，否则 move_email 会拒绝将邮件移入垃圾箱。

get_thread 会列出邮件所属的对话，即它所回复的邮件，以及引用了它或更早邮件的回复；搜索范围包括邮件所在文件夹、INBOX 和 Sent。随后，每封邮件都会通过 get_email 读取，并附带相应警告。create_draft 和 send_email 都支持使用 in_reply_to，让回复在邮件客户端中归入原邮件的对话。发送回复后，原邮件会标记为已回复。启用 quote_original 后，服务会像邮件客户端那样将原邮件内容附在回复下方，但前提是原邮件已包含所有收件人。原邮件 HTML 中隐藏的文本不会被引用。邮件正文最多为 64 kB，引用内容也计入其中。

search_emails 会分页返回结果，可按自由文本、from、to、subject、since 和 before 日期筛选，也可按未读或已标记状态筛选。get_email 会显示发送和到达时间、Cc，以及与 From 不同的 Reply-To。启用 manage 后，set_flags 可将邮件标记为已读、未读、已标记或未标记。

get_attachment 会将文件保存到 DOWNLOAD_DIR，而不会将其内容读入对话。保存的文件仅你可读取，且不会覆盖现有文件。在 macOS 上，保存的文件会带有隔离标记，因此其中的应用运行前会经过 Gatekeeper 检查。

永远无法做到的事

这些限制由服务端强制执行。

• 不会有原始 HTML 传到模型。只要邮件正文中有纯文本部分，就会使用该部分；否则会将正文转换为文本。会剥除不可见字符，防止它们在对读者隐藏指令的同时仍能被模型读取。
• 正文、主题、发件人名称和 Sieve 脚本都使用标记括起，且这些标记在内容中会被中和，因此邮件无法伪造内容越过边界。围栏外的行由服务端写入。任何在那里重复出现的短邮箱值（例如文件夹名称）都会先经过清理并限制长度。
• 草稿和已发送邮件都没有 bcc 字段。密送收件人会收到完整副本，却不会出现在邮件的任何位置，这正是被注入的邮件会要求的操作。
• 草稿和已发送邮件只能附加邮箱中已有的文件，并通过文件夹、uid 和 part 指定。没有任何工具会接收文件路径或附加磁盘中的文件。
• 删除操作会将邮件移至 Trash。没有清空或永久删除功能。无法移动邮件的服务端将被拒绝使用。之后提供商如何处理 Trash，由提供商决定。
• 有多个账户时，一次调用只会访问一个账户。附件、回复和引用内容都只来自调用中指定的账户，服务端也绝不会在账户之间移动邮件。
• Sieve 访问权限始终为只读。没有工具会写入筛选规则，因为这些规则即使在你撤销应用密码或卸载此服务后，仍可能转发邮件、自动回复和发送通知。

启用 send 后，发送功能仍处于关闭状态，除非 SEND_ALLOWLIST 中指定了收件人。它支持单个地址、形如 *@example.com 的域名，或单独使用 * 表示任何人。未设置允许列表时，拒绝信息会说明如何允许特定收件人或任何人。SEND_CONFIRM=true 会在每次发送前添加确认对话框，显示收件人、主题、附件和完整邮件内容（包括引用内容）。这需要支持 MCP elicitation 的客户端；其他客户端会被拒绝，因此请在这些客户端中使用草稿。Claude Desktop 目前尚不显示这些对话框（2026 年 10 月）。如果允许发送给任何人却不启用此功能，助手便可以未经询问就给任何人写信，这构成致命三要素中的第三项。设计说明见 SECURITY.md。

可疑内容警告

六种检测器会为 get_email 的结果添加标注，检测隐藏文本、指令模式、编码内容、发件人不匹配、多种文字混用和 DMARC 验证失败。Warnings 行位于内容上方，以服务端自己的措辞编写，绝不引用触发警告的内容。上方图片展示了一封邮件触发五种检测器的情况。

Warnings: hidden_text (412 hidden characters via display:none), encoded_blob (base64 run of 600 characters)

邮件始终会与警告一并返回。下方的配置参考中，每种检测器都有独立的开关。阈值、误报和 DMARC 信任选择详见检测器详情。

提供商设置

将 PROVIDER 设为 gmail、outlook、icloud、yahoo、gmx、fastmail、mailbox.org 或 posteo 之一，匹配的服务器和端口便会自动填入。

Gmail、iCloud、Yahoo 和 Fastmail 需要应用专用密码。Google 要求启用两步验证，且账户政策允许使用应用专用密码。iCloud 要求 Apple Account 启用双重认证。mailbox.org、GMX 和 Posteo 接受账户密码，不过使用应用专用密码更稳妥。

Outlook 和 Microsoft 365 使用 PROVIDER=outlook，无需密码。在 Outlook.com 中，前往 Settings、Mail、Forwarding and IMAP，开启 IMAP。首次读取邮件时，浏览器会打开 Microsoft 登录页面。登录并允许访问后，再次发起请求。

工作账户

你的组织可能需要管理员审批，发送邮件可能需要管理员启用 SMTP AUTH。有关同意链接和租户设置，请参阅工作账户。

完整的提供商指南介绍了密码、Microsoft 权限和退出登录、通过 Bridge 使用 Proton Mail，以及使用你自己的服务器。

配置参考

所有配置都通过环境变量设置。服务启动时会检查这些变量，因此拼写错误会立即导致报错，并提示需要修复的内容，而不是等到首次调用工具时才报错。空值视为未设置，因为捆绑包管理器会将留空的可选字段填充为空字符串。

多个账户

一个服务可以读取多个邮箱，所有邮箱共用一个发送上限；如果使用两个独立服务，则可以有两个发送上限。ACCOUNTS 用于指定账户，最多 10 个；每个账户的设置都要在变量名后加上 __ 和大写账户名，例如 EMAIL_USER__WORK。不设置 ACCOUNTS 时，行为不变。以下配置设置了一个个人 Gmail 账户，可起草邮件并向一个指定地址发送；另一个是工作 Outlook 账户，保留默认的读取和起草权限：

{
  "mcpServers": {
    "pylos-mcp": {
      "command": "npx",
      "args": ["-y", "pylos-mcp"],
      "env": {
        "ACCOUNTS": "personal,work",
        "PROVIDER__PERSONAL": "gmail",
        "EMAIL_USER__PERSONAL": "[email protected]",
        "EMAIL_PASSWORD__PERSONAL": "your-app-password",
        "CAPABILITIES__PERSONAL": "drafts,send",
        "SEND_ALLOWLIST__PERSONAL": "[email protected]",
        "PROVIDER__WORK": "outlook",
        "EMAIL_USER__WORK": "[email protected]"
      }
    }
  }
}

账户设置绝不会从不带后缀的变量中读取；设置了 ACCOUNTS 后，也会拒绝这些变量，因此，为某个账户设置的允许列表或权限永远不会应用到其他账户。MAX_BODY_KB、MAX_ATTACHMENT_MB、DOWNLOAD_DIR、SEND_SESSION_CAP、SEND_CONFIRM、DRAFTS_NO_RECIPIENTS、STRIP_HIDDEN_TEXT 和所有 FLAG_ 变量都适用于每个账户，且不带后缀。

每个工具都必须指定 account，并且只会列出具备相应权限的账户，因此在此配置中，send_email 仅提供 personal。不设默认账户，因为邮件编号只在所属邮箱内有意义。每条工具结果都以 Account: 开头，确保助手引用的内容始终关联到其来源账户。

配置错误会在启动时分组显示，并逐一指出需要修正的变量。这包括指定了 ACCOUNTS 中不存在的账户后缀，以及同一邮箱被配置两次（即相同 IMAP 主机上的相同 EMAIL_USER）。

Claude Desktop 安装包仅支持一个账户，因为其安装表单无法重复一组字段。要配置多个账户，请将上面的条目放入客户端的 JSON 配置中，包括 Claude Desktop 的 claude_desktop_config.json。

维护预期

pylos-mcp 是为作者日常使用而构建的，并按此目标维护。欢迎提交问题和拉取请求；CONTRIBUTING.md 列出了有助于改进项目的方向。

有关开发环境配置和测试，请参阅 CONTRIBUTING.md。无论在开发环境还是 CI 中，本项目的测试都不会连接真实邮箱。