MepMail

@mepmail/mcp

面向本地 MCP 客户端（Claude Desktop、Claude Code、Cursor、Codex 以及任何支持 stdio 的客户端）的官方 MepMail MCP 服务。它通过公开 REST API（兼容 Resend 的线路协议）和团队 API 密钥驱动你的 MepMail 实例；使用 Correio Agent 密钥时，还可操作你的邮箱：读取收件箱、将回复保存为草稿并发送（或请所有者审批）。

MepMail 还提供托管 MCP 服务（OAuth，无需安装），地址为 https://api.mepmail.dev/mcp。此软件包适用于通过配置启动本地服务的 客户端。工具名称和结果格式与托管服务一致；此软件包涵盖其中一部分——读取、发送和联系人工具（22 个）——而联系人之外的写入功能（细分群组、主题、群发、模板、webhook、域名、API 密钥）以及团队选择器仅在托管服务中提供。

指南：https://docs.mepmail.dev/mcp · 软件包：https://docs.mepmail.dev/packages · 发布于 npm，名称为 @mepmail/mcp。

需要 Node.js 20 或更高版本。

快速入门

1. 在 MepMail 控制面板中创建 API 密钥（API keys）——使用完全访问权限 的密钥，也可以将其限定为 Agent 发信所用的发件人域名。发送权限密钥仅限访问 /emails，因此使用联系人 工具（list_contacts、get_contact、create_contact、update_contact、 delete_contact）时会因 restricted_api_key 返回 403。
2. 将服务添加到你的客户端：

Claude Desktop（claude_desktop_config.json）——以及任何配置格式相同的客户端（Cursor：mcp.json）：

{
  "mcpServers": {
    "mepmail": {
      "command": "npx",
      "args": ["-y", "@mepmail/mcp"],
      "env": {
        "MEPMAIL_API_KEY": "ms_...",
        "MEPMAIL_BASE_URL": "https://api.mepmail.dev"
      }
    }
  }
}

Claude Code：

claude mcp add mepmail -e MEPMAIL_API_KEY=ms_... -e MEPMAIL_BASE_URL=https://api.mepmail.dev -- npx -y @mepmail/mcp

Correio 邮箱——前往 Correio → Settings → Agents 创建 Agent 密钥： mmb_... 用于单个邮箱；也可选择“Connect an agent to several mailboxes”，创建一个可用于所选邮箱的 mmt_... 凭据，并授予读取、草稿及可选的发送权限。然后将其添加到同一服务中（如果只需使用邮箱，API 密钥可选）：

claude mcp add mepmail -e MEPMAIL_MAIL_TOKEN=mmt_... -- npx -y @mepmail/mcp

环境变量

至少设置 MEPMAIL_API_KEY 和 MEPMAIL_MAIL_TOKEN 中的一个。

变量	必需	默认值	含义
MEPMAIL_API_KEY	发送工具需要	—	团队 API 密钥（ms_...）。仅向你的实例发送，作为 Bearer 传递。
MEPMAIL_BASE_URL	否	https://api.mepmail.dev	你的实例 API URL。
MEPMAIL_MAIL_TOKEN	邮箱工具需要	—	Correio Agent 密钥（mmb_... 或 mmt_...）。仅向控制面板来源发送，作为 Bearer 传递。
MEPMAIL_MAIL_ORIGIN	否	https://mepmail.dev	控制面板响应请求的位置。

工具（22）

发送和管理邮件：

• send_email — 发送或安排发送一封事务性邮件（cc/bcc/reply_to、标签、 附件、按主题限定的发送）。
• send_email_batch — 一次调用最多发送 100 封邮件。
• get_email、list_emails — 状态和时间线（last_event：delivered、 bounced、complained 等）。
• update_email、cancel_email — 重新安排或取消已安排的邮件。
• get_email_insights — 单封邮件的最佳实践报告和评分。
• get_deliverability、get_usage — 批量操作前查看账户状态。

受众和账户：

• create_contact、update_contact、delete_contact（使用 erase=true 执行 GDPR/LGPD 数据清理）、get_contact、list_contacts — 支持细分筛选。
• list_domains、get_domain — DNS 记录和验证状态。
• list_broadcasts、get_broadcast。
• list_templates、get_template。
• list_webhooks、list_suppressions。

Correio 邮箱（使用 MEPMAIL_MAIL_TOKEN，与托管服务 https://api.mepmail.dev/mcp/correio 提供的五个工具相同）：

• mailbox_list_accounts — 此密钥可访问的邮箱及其权限和默认邮箱。
• mailbox_list_messages、mailbox_read_message — 收件箱、草稿和已发送邮件； 使用团队凭据时需传入 mailbox。列表每次返回一页，按最新时间优先：将返回的 nextCursor 作为 cursor 传入，直到 hasMore 为 false（游标仅适用于相同的 邮箱、文件夹和筛选条件）。筛选条件会在服务器上应用，然后再截取页面： query（单词、“带引号的短语”、de:/from:、para:/to:、 assunto:/subject:、tem:anexo、depois:/antes:）、from、 subject、unread、after、before；limit 最高为 100（搜索时为 50）。 翻页期间收到的邮件会排在第一页之前，因此要查看这些邮件，请从头开始。 页面较短或为空，不能证明邮箱中不存在某封邮件；搜索会读取可能比新邮件延迟约 一分钟的索引。日期方面：列表中的 after/before 使用排序时间（邮件到达时间、 延后处理的邮件恢复时间，或草稿的最后编辑时间）；搜索使用到达时间，而且搜索 也会找到延后处理的邮件，而列表会将其排除，直到这些邮件恢复。
• mailbox_get_attachment — 根据邮件 ID、版本和索引（来自 mailbox_read_message）获取一个附件：文件名、字节内容和 sha256。设置 MEPMAIL_MAIL_DOWNLOAD_DIR 后，文件会保存到该目录（绝不覆盖现有文件）； 否则会以 content_base64 返回，大小上限为 512 KiB。
• mailbox_save_draft — 从该邮箱的地址和签名创建新草稿、编辑草稿、回复或转发。 attachments 可用 { filename, content_base64 } 添加文件，也可使用 { path } 指定 MEPMAIL_MAIL_UPLOAD_DIR 内的文件（不会读取其他本地路径）；keep_attachments 用于选择要保留的已编辑草稿或转发邮件中的文件（默认全部保留；回复不保留附件）。 限制：最多 10 个文件，每个文件不超过 256 KiB，总计约 700 KiB。文件只会随草稿 请求传输，因此放弃草稿时不会留下任何文件。
• mailbox_send_draft — 使用发送权限发送；否则所有者会收到审批请求 （awaiting_approval）。

每个工具结果都是一个 JSON 块封装 — { notice, untrusted_data } — 因此 Agent 可以区分团队撰写的字符串和工具输出，且绝不会将收件人数据视为指令。

发送时安全重试

send_email 和 send_email_batch 接受可选的顶层 idempotency_key。重试同一发送操作时，请使用相同的键和完全相同的参数。新操作请生成新键。服务端会将其作为 HTTP Idempotency-Key 标头传递；它不是电子邮件标头或消息字段。

键的作用范围限定为团队，并保留 24 小时。重试已完成的操作会返回原始结果。使用相同的键但传入不同参数会返回冲突；仍在进行中的操作也可能返回冲突。不完整的预留可在 10 分钟后恢复。这些限制由服务端执行，因此请使用支持此约定的 API 版本。

Agent 发现

• 机器目录：https://mepmail.dev/.well-known/ai-catalog.json
• Agent 身份验证指南：https://mepmail.dev/auth.md
• API、错误和速率限制：https://docs.mepmail.dev

许可证

MIT