mailbox-mcp

mailbox-mcp 是一款 MCP 服务，可将电子邮件连接到 Claude Code、Cursor、Windsurf，或任何支持 Model Context Protocol 的 AI 工具。无需在终端和 Gmail 之间来回切换，只需让 AI 查找发票、总结邮件会话或起草回复即可。

它与其他 60 多款电子邮件 MCP 服务的不同之处：

• 多个账户，一个服务。 工作邮箱、个人邮箱、客户账户——都可通过一个服务访问。无需运行多个实例。
• 不只是 Gmail。 支持 Gmail（完整 API）、任何 IMAP/SMTP 服务商（ProtonMail、企业邮件、可自托管邮件），以及 JMAP（Fastmail、Stalwart、Topicbox）。添加服务商无需修改任何工具代码。
• 为处理不可信输入而构建。 清除隐藏文本、随机 nonce 围栏、邮件发出账户前的确认、按账户设置只读和仅草稿模式、加密凭据（AES-256-GCM）、强制使用 TLS、SSRF 防护。详见安全性。
• 提供实用工作流所需的工具。 搜索、阅读、发送、回复、转发、草稿、标签、筛选器、模板、签名、休假自动回复、附件、取消订阅等。
• 零原生依赖。 纯 Node.js。可在任何地方安装和运行。

安全性

让模型访问邮箱，就意味着让它接触陌生人写下的文本。任何发件人都可以控制模型所读取邮件的主题、正文、标头和附件文件名，因此有两种风险：模型遵循植入邮件中的指令，以及模型将邮件发送到不该发送的地方（这类指令通常会要求转发邮件会话、回复并附上另一封邮件的内容，或将秘密发送到外部地址）。mailbox-mcp 在这两者之间设置了多重防护。

用围栏标记不可信内容。 所有来自电子邮件的内容都会被包裹在 [UNTRUSTED_<KIND>_<nonce>] ... [/UNTRUSTED_<KIND>_<nonce>] 标记中，服务的 MCP 指令会告知客户端，标记内的文本只是需要转述的数据，绝不是需要遵循的指令。nonce 是每次工具响应都会重新生成的随机十六进制字符串，因此邮件无法提前关闭围栏或伪造围栏；内容中任何看起来像标记的文本，无论大小写如何或是否使用 Unicode 形近字符，都会在传给模型前替换掉方括号。

移除隐藏文本，并告知你。 仅含 HTML 的邮件会精简为邮件客户端实际显示的内容。会移除使用 display:none、visibility:hidden、opacity:0、零或近乎为零的字号、与背景同色的文本（白底白字）、hidden 属性、aria-hidden、屏幕外定位以及预览文本 max-height:0; overflow:hidden 技巧隐藏的元素，同时也会移除注释、脚本、样式和模板。所有正文、主题、标头和文件名中的零宽字符及双向控制字符都会被剥除。若移除了任何内容，响应末尾会显示警告，说明移除了多少个字符。因此，邮件对你说一套、对模型说另一套时，会被标记出来，而不是悄无声息地清理。 邮件发出前确认。 向账户从未发送过邮件或从未收到过邮件的地址发送邮件，需要设置 confirm_new_recipient: true；错误信息会列出这些新地址。转发到账户所属域名以外的域名，需要设置 confirm_external_forward: true。系统会告知客户端：只有当你亲自要求联系该收件人时才传递这些标记，绝不能因为邮件提出了要求就传递。默认启用这两项检查。

按账户设置模式。 账户可以设置收件人允许列表（精确地址和 @domain 模式；其他所有地址都会被拒绝）、draftsOnly 标记（发送工具会改为创建草稿供你审核）和 readOnly 标记（所有写入工具都会拒绝；搜索和读取仍可正常使用）。这些设置可在 accounts.json 中配置，也可在创建账户时设置；任何工具都无法放宽这些限制，因此被劫持的会话无法将其关闭。参见账户安全设置。

工具注释。 全部 49 个工具都带有 MCP readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint 注释，客户端因此可以自动批准读取操作，并始终在发送、删除或更改设置前询问。

限额与日志。 每分钟最多发送 10 封邮件；默认情况下，每个账户在任意滚动 24 小时内最多发送 100 封。每日计数会保存到磁盘，重启后仍会保留。通过服务发送的每封邮件都会连同收件人记录到 ~/.mailbox-mcp/sends.jsonl；每次批量标签或移至垃圾箱的操作都会连同撤销 ID 记录到 transactions.jsonl。

以下三个选项会在模型之外强制执行限制，而不是要求模型自行遵守。它们默认都处于关闭状态。

带外审批（按账户设置 "approval": "external"）。所有发送路径仍会执行上述防护检查，然后将完整解析后的邮件写入 ~/.mailbox-mcp/pending/<id>.json，而不是发送，并将 ID 告知模型。任何工具都无法列出、编辑或批准该队列。你需要在终端中执行：mailbox-mcp pending、mailbox-mcp show <id>、mailbox-mcp approve <id>、mailbox-mcp reject <id>。approve 会打印完整邮件，从 /dev/tty 读取确认（而非 stdin，因此无法通过管道输入），重新检查允许列表和每日限额，重新加载附件并在附件发生变化时拒绝操作，然后准确发送打印出的内容。没有控制终端的 shell（Agent 的 shell 就是这种情况）无法打开 /dev/tty，因此无法批准自己发出的邮件。条目会在 7 天后过期。参见批准排队的发送。

工具配置（MAILBOX_MCP_PROFILE）。read 仅提供只读工具；draft 提供除可能导致邮件发出账户的工具以外的所有工具。隐藏的工具不会出现在工具列表中，即使被调用也会拒绝执行。参见选择要加载的工具。

读取不可信内容后锁定（按账户设置 "untrustedReadLock": "approval" | "refuse"）。只要工具向模型展示了无法验证可信性的邮件，或将邮件内容导出或下载到磁盘，该账户就会在本次服务进程的剩余时间内被标记。此后，即使未设置 approval，approval 也会将该账户的所有发送操作转入待处理队列；refuse 则会拒绝发送，直到服务重启。模型无法通过传递任何参数解除锁定。此锁定有意采用严格标准：只有当发件人位于账户 accounts.json 中的 trustedSenders 列表内，且接收方服务器对发件人域名的 DMARC 检查通过时，邮件才会被视为可信。发件人或模型能影响的任何内容都不计入判断：包括 From 标头、Sent 文件夹、发送日志和邮箱搜索结果。如果未配置 trustedSenders，读取任何第三方邮件都会触发标记，这是预期的默认行为；大多数人会更适合使用 approval: "external"，而不是维护很长的可信列表。参见锁定判定方式。 这些措施都无法让提示词注入变得不可能。模型仍可能被诱导着给出你不想要的回复，而 text/plain 部分可能会写出与人类看到的 HTML 部分不同的内容。发送时应保留人工审批。一种合理的配置是：对只需搜索的账户设置 readOnly: true 或 MAILBOX_MCP_PROFILE=read；对 Agent 在无人值守情况下发送邮件的账户，设置 approval: "external" 或使用允许列表；对任何会整理收件箱的账户设置 untrustedReadLock；其他所有情况则使用默认确认设置。

快速开始

安装

将以下内容添加到 Claude Code MCP 配置文件（~/.claude.json）中。该软件包可通过 npx 直接从 npm 运行：

{
  "mcpServers": {
    "mailbox": {
      "command": "npx",
      "args": ["-y", "mailbox-mcp"],
      "env": {
        "MAILBOX_MCP_PASSPHRASE": "a-long-random-passphrase"
      }
    }
  }
}

MAILBOX_MCP_PASSPHRASE 是用于加密静态存储的 IMAP/JMAP 凭据的密码；添加 IMAP 或 JMAP 账户前必须设置此变量，仅使用 Gmail 时无需设置。MAILBOX_MCP_CONFIG_DIR 可将配置目录移至 ~/.mailbox-mcp 以外的位置。

git clone https://github.com/jgalea/mailbox-mcp.git
cd mailbox-mcp
npm install && npm run build

添加 Gmail 账户

1. 创建 Google Cloud 项目

1. 前往 Google Cloud Console 并创建新项目
2. 启用 Gmail API：APIs & Services > Library > Gmail API > Enable

2. 设置 OAuth 同意屏幕

1. 前往 Google Auth Platform > Branding
2. 设置 App name 和 User support email
3. 前往 Audience，选择 External
4. 将用于登录的 Google 账户添加为测试用户（必须使用用于身份验证的确切 @gmail.com 地址，不能使用 Workspace 别名）

3. 创建 OAuth 凭据

1. 前往 Google Auth Platform > Clients > Create Client
2. Application type：Desktop app
3. 点击 Create
4. 前往 APIs & Services > Credentials，找到你的客户端，然后点击下载图标获取 JSON 文件
5. 将文件保存为 ~/.mailbox-mcp/oauth-keys.json

4. 进行身份验证

在 Claude Code 中运行：authenticate alias="personal" provider="gmail" email="[email protected]"

这会打开浏览器窗口以完成 OAuth 流程。令牌会存储在本地的 ~/.mailbox-mcp/accounts/ 中。

添加 IMAP 账户

在 Claude Code 中运行：

authenticate alias="work" provider="imap" email="[email protected]" host="imap.company.com" smtpHost="smtp.company.com" username="[email protected]" password="<app-password>"

凭据使用 AES-256-GCM 加密后静态存储。

添加 JMAP 账户

在 Claude Code 中运行：

authenticate alias="fastmail" provider="jmap" email="[email protected]" host="fastmail.com" username="[email protected]" password="<app-password>"

JMAP 会通过 .well-known/jmap 自动发现 API 端点。凭据使用 AES-256-GCM 加密后静态存储。

支持的 JMAP 服务： Fastmail、Stalwart、Topicbox、Cyrus IMAP，以及任何符合 RFC 8620 的服务。

JMAP 相较于 IMAP 的优势：

• 原生线程支持（真实对话，而非合成对话）
• 服务端搜索（速度更快、准确度更高）
• 单个 HTTP 请求即可执行批量操作
• 无需持久连接

工具

通用（Gmail + IMAP + JMAP）

仅限 Gmail

账户安全设置

~/.mailbox-mcp/accounts.json 中的每个条目都可以包含以下 8 个可选字段：

{
  "accounts": {
    "archive": { "provider": "gmail", "email": "[email protected]", "readOnly": true },
    "agent": {
      "provider": "imap", "email": "[email protected]",
      "host": "imap.example.com", "port": 993, "smtpHost": "smtp.example.com", "smtpPort": 587,
      "allowedRecipients": ["[email protected]", "@example.com"],
      "dailySendLimit": 20
    },
    "personal": { "provider": "gmail", "email": "[email protected]", "draftsOnly": true },
    "work": { "provider": "gmail", "email": "[email protected]", "approval": "external", "untrustedReadLock": "approval" },
    "triage": { "provider": "gmail", "email": "[email protected]", "untrustedReadLock": "refuse", "trustedSenders": ["[email protected]", "@partner.example"] }
  }
}

创建账户时，可以将相同设置作为 read_only、drafts_only、allowed_recipients、daily_send_limit、approval 和 untrusted_read_lock 参数传递给 authenticate，而且 list_accounts 会显示这些设置。此后不会提供用于更改这些设置的工具：请编辑文件并重启服务。若条目格式不正确，服务会拒绝启动，而不会在缺少防护的情况下运行。

批准排队发送

运行服务的同一个二进制文件也是批准 CLI。不带参数时，它会启动 MCP 服务；带命令时，它会处理队列并退出。

mailbox-mcp pending        # id, account, from, recipients, subject, created, attachment names
mailbox-mcp show <id>      # the full message
mailbox-mcp approve <id>   # prints the message, asks "Type yes to send", sends exactly that
mailbox-mcp reject <id>    # drops it

如果通过 npx 安装，请运行 npx mailbox-mcp pending 等命令。配置目录与服务使用的相同（MAILBOX_MCP_CONFIG_DIR，默认为 ~/.mailbox-mcp），因此如果更改过该目录，请以相同方式设置。

approve 会从 /dev/tty 读取确认信息，而非 stdin；如果无法打开该设备，则会明确报错并拒绝操作。这样可以阻止拥有 shell 访问权限的 Agent 批准自己发送邮件：它的 shell 没有控制终端。它显示什么，就会发送什么：队列条目只会通过一个拒绝符号链接的文件描述符读入内存一次，并且会在发送前再次检查文件哈希。若邮件包含终端转义序列、双向文本控制符或零宽字符，可能导致屏幕显示内容与实际发送内容不一致，则会直接拒绝。在批准时，它会根据当前的 accounts.json 重新检查允许列表和每日上限，从队列创建时记录的路径重新加载每个附件；如果文件不存在或大小发生变化，就会拒绝发送。它会像其他发送操作一样将发送记录写入 sends.jsonl，并删除待处理文件。超过 7 天的条目会被拒绝；请将其驳回以完成清理。待处理目录的权限为 0700，文件的权限为 0600。

对于回复和转发，排队的正文就是你的文本；线程标头和转发的原始邮件会由提供方在发送时添加，正如 show 所述。对于 send_draft，队列会保存草稿 ID、收件人，以及草稿当时内容的指纹；如果草稿或其收件人在排队后发生变化，approve 会拒绝发送，因此排队后执行的 update_draft 无法沿用先前的审核结果。请在邮件客户端中检查正文。

如果 Agent 在 Claude Code 中运行，请将批准命令添加到 .claude/settings.json 的拒绝列表中，这样即使出现权限提示，也不会提供该命令：

{ "permissions": { "deny": ["Bash(mailbox-mcp approve*)", "Bash(npx mailbox-mcp approve*)"] } }

“新收件人”的判定方式：如果此服务此前曾从该账户向某地址发送过邮件（记录在 sends.jsonl 中），该地址是账户自己的地址，或者一次提供方搜索（from:addr OR to:addr，最多返回一条结果；IMAP 仅搜索 INBOX）找到了邮件，则该地址为已知地址。其他地址都需要设置 confirm_new_recipient: true。从所回复邮件中获取的回复目标地址视为可信，因为你已经收到过他们的邮件。

authenticate 会拒绝已存在的别名，无论是否设置了安全选项，从而防止会话在该别名下替换地址、提供方或主机；reauth 会刷新 Gmail 令牌，但不会修改配置。remove_account 会拒绝移除任何设置了安全选项的账户，因为移除后重新添加会导致这些选项丢失。这两个命令都会操作 accounts.json。模型可调用的任何功能也都无法写入配置目录或日志目录：export_email、export_thread 和 download_attachment 会拒绝将 save_to 指向这些目录内（即使该目录位于 /tmp 下、在不区分大小写的文件系统上使用了不同大小写拼写，或通过符号链接访问），只会写入经过验证的规范目录；目录存在后会再次检查，并且绝不会通过被放置在文件名下的符号链接写入；发送操作的 attachments 也会遵循相同规则，拒绝从这些目录读取。因此，批准队列、accounts.json、发送日志和存储的凭据都不会被触及。发送操作的每个收件人都必须是单个普通地址；如果一个值包含两个地址，则会直接拒绝，而不是仅检查其中第一个地址。

锁的判定方式

只有同时满足以下所有条件时，untrustedReadLock 才会将邮件视为可信。From 标头解析后必须恰好得到一个普通地址（存在多个地址、显示名称中带有自己的尖括号或 @、不可见字符，或完全没有地址，都会导致判定失败）。该地址必须与账户的 trustedSenders 中某个条目匹配（完整地址或 @domain；仅匹配域名，不匹配子域名）。最顶部的 Authentication-Results 标头必须由账户自己的服务器写入（authserv-id 等于 authservId；Gmail 为 mx.google.com），其中必须恰好包含一个 dmarc= 结果，该结果必须为 pass，且其 header.from 必须与 From 域名相同。其他所有情况都会被视为不可信：不在列表中的发件人、虽在列表中但邮件未通过 DMARC 验证的发件人、账户自己的地址（除非已列入名单）、来自你未在 authservId 中指定的服务器的邮件、无法提供邮件标头的任何工具，以及判定过程中的任何错误。Sent 文件夹、本地发送日志和邮箱搜索都不参与判定，因为工具调用可以更改标签和文件夹，而搜索结果可能受到伪造邮件的影响。导出和下载一律视为不可信，因为内容会离开保护范围。

选择要加载的工具

对于会将所有定义加载到上下文中的客户端，49 个工具架构大约会消耗 6,000 个 token。日常使用中，少数几个工具就能完成大部分工作，因此你可以通过 MAILBOX_MCP_TOOLS（逗号分隔）只公开所需的组。不设置时会加载所有工具。

"env": {
  "MAILBOX_MCP_TOOLS": "core,attachments"
}

调用已禁用组中的工具时会失败，并显示需要启用的组名。

工具配置

MAILBOX_MCP_PROFILE 用于选择实例类型。它与 MAILBOX_MCP_TOOLS 共同生效：只有两者都允许加载的工具才会加载。隐藏的工具不会出现在工具列表中，即使调用也会被拒绝，并显示配置名称。未知值会导致服务在启动时停止。

draft 会隐藏以下工具，因为它们都可能使邮件离开账户，或更改今后发给第三方的邮件内容：send_email、reply_email、forward_email、send_draft、send_template（这些工具会发送邮件）；create_filter（Gmail 过滤器可以转发邮件并自动归档）；set_vacation（会发送自动回复）；set_signature（会将文本注入你今后发送的每封邮件）；unsubscribe 和 bulk_unsubscribe（会显示由攻击者选择的退订目标，供你操作）。草稿、标签、归档、移至垃圾箱、支持撤销的批量操作、下载和导出仍可使用。

"env": { "MAILBOX_MCP_PROFILE": "draft", "MAILBOX_MCP_TOOLS": "core,attachments" }

使用 Jev 进行收件箱分类（可选）

将 MAILBOX_MCP_TYPESAFE_API_KEY（或 TYPESAFE_API_KEY）设置为来自 TypeSafe 的密钥，inbox_summary 就会为每封近期邮件添加标签：需要回复、供参考、新闻简报、收据、通知或可疑邮件；如果发件人需要在大约一天内得到回复，还会标记为紧急，并附上置信度。

"env": { "MAILBOX_MCP_TYPESAFE_API_KEY": "your-key" }

Jev 是一个决策模型：它只能从上述固定选项中选择，因此邮件中的文本无法诱导它执行其他操作。标签仅来自这些固定选项，绝不会来自邮件文本，并且会显示在不可信内容围栏之外。

此功能会将每封邮件的发件人、主题和摘要（最多 2,000 个字符）发送到 TypeSafe API。密钥留空时不会发送任何内容；工具的行为与之前完全相同。每次调用最多分类 25 封邮件；任何处理失败的邮件都会报告为未分类，而不会猜测。

发送附件

send_email、reply_email、forward_email 和 create_draft 接受可选的 attachments 参数，即本地文件路径数组。服务端会读取每个文件，根据扩展名检测其 MIME 类型，并将其嵌入外发邮件（或草稿）中。

send_email account="personal" to=["[email protected]"] subject="The report" body="See attached." attachments=["/path/to/report.pdf", "/path/to/chart.png"]

• 每个文件必须是常规文件且不超过 25 MB；每封邮件的附件总大小上限为 25 MB（Gmail 的硬性限制）。
• 路径会解析所有符号链接，并在文件名写入标头前移除 CRLF。
• Gmail 会通过多部分上传端点（API 限制为 35 MB）发送带附件的邮件，而不是使用 JSON 端点，因此 25 MB 的邮件上限才是真正的限制。
• JMAP 会先将每个文件上传到服务端的上传 URL，然后在 Email/set 调用中引用生成的 blobIds。

选择发件人地址

一个账户通常会使用多个地址发送邮件。send_email、reply_email、forward_email、create_draft 和 update_draft 接受可选的 from 参数；未指定时会使用账户的主地址。

reply_email account="personal" message_id="18f..." from="[email protected]" body="Thanks, sorted."

接受的格式为 [email protected] 和 Name <[email protected]>；匹配时不区分大小写。

发送前会对照账户检查地址；如果地址不匹配，调用会失败并列出可用地址。这一点很重要，因为当 From 标头中指定了未经验证的地址时，Gmail 会静默回退到主地址，因此邮件可能会以错误的身份发出，却看起来像是成功了。有些收件人（例如 Amazon 客户服务）会拒收发件地址与存档地址不一致的邮件。

• Gmail：该地址必须是已完成验证的发件别名。运行 list_send_as 查看这些地址。待验证的别名会被拒绝。
• JMAP：该地址必须与账户的某个身份匹配；提交时会附加其 identityId。
• IMAP：没有别名列表可供核对，因此任何 from 值都会传递给 SMTP 中继，由其在发送时接受或拒绝。

许可证

MIT

由 AgentVania 打造。