Email Mcp

@marlinjai/email-mcp

一个统一的 MCP 服务，可通过 Gmail、Outlook、iCloud 和通用 IMAP 服务商访问电子邮件。

功能

• 支持多种服务商 —— Gmail（REST API）、Outlook（Microsoft Graph）、iCloud（IMAP）以及通用 IMAP/SMTP
• OAuth2 身份验证 —— 为 Gmail 和 Outlook 提供基于浏览器的 OAuth 流程，并自动刷新令牌
• 完整的电子邮件客户端 —— 搜索、阅读、发送、回复、转发、整理邮件并管理草稿
• 批量操作 —— 一次调用即可删除、移动或标记数百封邮件
• 轻量级搜索 —— 默认提供精简的搜索结果（约 20KB，而非约 1.4MB），也可按需获取完整邮件正文
• 加密凭据存储 —— 使用 AES-256-GCM 加密静态凭据，并通过机器生成密钥
• 原生服务商 API —— 在可用时使用 Gmail API 和 Microsoft Graph 以提供更丰富的功能；同时支持回退到 IMAP，以实现通用兼容性

安装

从 npm 全局安装：

npm install -g @marlinjai/email-mcp

或者使用 npx 直接运行（无需安装）：

npx @marlinjai/email-mcp

快速开始

1. 运行交互式设置向导，添加电子邮件账户：

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

必须使用 -p/--package 标志。 此软件包声明了两个可执行程序（MCP 服务使用的 email-mcp，以及此向导使用的 email-mcp-setup）。如果不使用 -p，npx 会运行与软件包自身名称匹配的可执行程序（email-mcp，即服务），并将 email-mcp-setup 作为被忽略的参数静默传递给它；随后服务会一直等待从 stdin 输入 MCP 协议内容，完全不产生任何输出。看起来就像卡住了一样。-p 会明确告知 npx 要解析哪个软件包，以及实际运行其中的哪个可执行程序。

向导会引导你选择服务商并完成身份验证。添加每个账户后，它都会询问你是否要继续添加账户，因此你可以一次性设置 Gmail、Outlook 和 iCloud。

2. 将服务添加到 MCP 配置（.mcp.json）：

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}

3. 在 Claude Code 中开始使用电子邮件工具——搜索收件箱、发送邮件、整理邮件等。

服务商设置指南

Gmail

无需配置 — 设置向导会使用内置的 OAuth 凭据（PKCE）处理所有事项：

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Gmail" when prompted
# Choose "Full" or "Restricted" permission scope when asked
# A browser window opens for Google authorization
# Grant the requested permissions and return to the terminal

向导会询问要授权哪个 Gmail 权限范围：

• 完整（默认）— 包含下述所有权限，以及立即绕过废纸篓永久删除邮件的权限（https://mail.google.com/，Gmail 的最高权限范围）。
• 受限 — 可读取、发送、添加标签、归档和移至废纸篓（gmail.modify + gmail.settings.basic），但不能永久删除。此服务中的所有工具在受限范围下均可正常工作，唯独显式设置 permanent: true 的删除操作会失败并返回 Gmail API 错误，而不是成功执行。

传入 --scope full 或 --scope restricted 可跳过提示，或者在运行向导的环境中设置 EMAIL_MCP_GMAIL_SCOPE=restricted。

验证状态（2026 年 10 月 1 日）： Google 对共享 OAuth 应用的审核仍在进行，因此目前只有测试用户列表中的账号可以通过该应用登录；其他用户会看到“尚未完成 Google 验证流程”的页面，需要使用自己的 OAuth 应用（见下一条说明）。共享应用尚未完成的最后一步是 Google 要求进行的年度独立安全评估（CASA，Cloud Application Security Assessment）。由于 email-mcp 没有自己的服务端，目前正在与 Google 确认此要求是否适用。详情和最新状态：email.lumitra.co/privacy#google-verification，进度记录见 issue #1。

注意： 如果你希望使用自己的 OAuth 应用，而不是此软件包附带的共享应用，请在 Google Cloud Console 中创建一个启用了 Gmail API 的 Desktop OAuth 2.0 Client，然后在运行设置向导前，在环境中设置 EMAIL_MCP_GMAIL_CLIENT_ID 和 EMAIL_MCP_GMAIL_CLIENT_SECRET（MCP 服务的环境中也要设置，因为重新授权会使用相同的变量）。这样，你可以拥有独立于发布者 Cloud 项目的令牌生命周期；在自己的应用中将自己添加为测试用户后，也可以避免 Google 的未验证应用警告和 100 个测试用户上限对自己账号的限制。

Outlook

无需配置 — 设置向导会使用内置的 OAuth 凭据（PKCE）处理所有事项：

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Outlook" when prompted
# A browser window opens for Microsoft authorization
# Sign in and grant the requested permissions

注意： 如果你希望使用自己的 OAuth 应用，请在 Azure Portal 中注册一个应用，并配置 Mail.ReadWrite、Mail.Send、MailboxSettings.ReadWrite（email_create_block_rule 所需）和 offline_access 权限，然后在运行设置向导前，在环境中设置 EMAIL_MCP_OUTLOOK_CLIENT_ID。

iCloud

1. 前往 appleid.apple.com 并登录。
2. 转到 App-Specific Passwords，生成一个新密码。
3. 运行设置向导：

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "iCloud" when prompted
# Enter your iCloud email address
# Enter the app-specific password you generated

通用 IMAP

使用你的 IMAP/SMTP 服务端详情运行设置向导：

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Other IMAP" when prompted
# Enter your IMAP host, port, and credentials
# Optionally enter SMTP host and port for sending

可用工具（36）

账号管理（4）

工具	描述
email_list_accounts	列出所有已配置账号及其连接状态
email_add_account	添加新的 IMAP 或 iCloud 账号（Gmail/Outlook 需要使用设置向导）
email_remove_account	移除账号及其存储的凭据；撤销 Gmail 的 Google 授权，从本地令牌缓存中移除 Outlook 令牌，并报告处理结果
email_test_account	测试与账号的连接

阅读与搜索（6）

工具	描述
email_list_folders	列出帐户的所有文件夹/标签
email_search	使用筛选条件搜索邮件。默认返回精简结果（returnBody=false）。将 returnBody=true 设置为包含完整邮件正文
email_get	按 ID 获取完整邮件内容（邮件头、正文、附件元数据）。当邮件不在 INBOX 中时，sourceFolder 指定 iCloud/IMAP 上的文件夹名称
email_get_thread	获取整个邮件线程/对话。在 iCloud/IMAP 上，线程只会在一个文件夹中搜索：INBOX，或 sourceFolder 中指定的文件夹
email_get_attachment	按 ID 下载指定附件（返回 base64 数据）。当邮件不在 INBOX 中时，sourceFolder 指定 iCloud/IMAP 上的文件夹名称
email_save_attachment	将附件直接下载到磁盘，只返回元数据，从而避免将大型文件以 base64 格式来回传输所产生的令牌开销。outputPath 相对于固定的下载目录（~/.email-mcp/downloads，可通过 EMAIL_MCP_DOWNLOADS_DIR 覆盖），且不能超出该目录。sourceFolder 的含义与 email_get_attachment 相同

发送与草稿（6）

email_send、email_reply、email_forward、email_draft_create 和 email_draft_update 都可选接受 attachments 列表。每个条目可以是 { path }（附件文件夹中的文件，见下文），也可以是 { content, filename }（base64），还可选包含 contentType（否则根据扩展名推断）。总大小上限为 25 MB；通过此服务发送时，Outlook 每封邮件最多接受 3 MB。对于 email_draft_update，提供列表会替换草稿中的文件，空列表会移除文件，不提供列表则保留草稿现有文件。

回复会保留在原线程中：email_reply 会在 Gmail 和 Outlook 的原始对话中发送回复（并在所有平台设置 In-Reply-To 和 References 标头）；使用 inReplyToEmailId 调用 email_draft_create 会在该线程中保存回复草稿；email_draft_update 则会让回复草稿继续留在该线程中。

转发原始邮件的附件需要显式启用。 email_forward 会发送原始邮件的文本；只有设置 includeOriginalAttachments: true 才会一并发送原始邮件的文件，避免一次调用将助手从未查看过的文件发送到其他地址。转发的文件和新增文件会一并计入 25 MB 上限。

按路径附加文件的功能默认关闭，直到你指定文件夹。 路径由助手提供，而能够读取邮件的助手可能会收到邮件指示，附加不应附加的内容（例如私钥）。因此，只会从你在服务环境中通过 EMAIL_MCP_ATTACHMENTS_DIR 设置的一个文件夹读取文件；任何工具都无法更改该设置。将文件放入该文件夹，然后按名称请求：

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"],
      "env": { "EMAIL_MCP_ATTACHMENTS_DIR": "~/Documents/email-outbox" }
    }
  }
}

文件夹之外的路径会被拒绝，指向文件夹之外的符号链接也会被拒绝；此外，email-mcp 自身的数据文件永远无法作为附件。

工具	描述
email_send	撰写并发送新邮件（to、cc、bcc、subject、body、attachments）
email_reply	在线程中回复邮件。replyAll 会向发件人以及所有 To/Cc 收件人发送回复，但会排除你自己的地址，并且每个地址只添加一次。可选的 to/cc/bcc 覆盖项和 additionalRecipients，例如回复自己发送的邮件时使用。支持附件。如果邮件不在 INBOX 中，sourceFolder 用于指定 iCloud/IMAP 上的文件夹
email_forward	将邮件转发给新收件人（to、cc、bcc、顶部可选文本、附件）。除非设置 includeOriginalAttachments: true，否则不包含原始邮件的附件。如果邮件不在 INBOX 中，sourceFolder 用于指定 iCloud/IMAP 上的文件夹
email_draft_create	保存草稿但不发送（支持附件）。设置 inReplyToEmailId 可将草稿保存为该邮件线程中的回复（如果邮件不在 INBOX 中，inReplyToSourceFolder 用于指定 iCloud/IMAP 上该邮件所在的文件夹）
email_draft_update	就地更新现有草稿。回复草稿会保留在线程中。在 Gmail/Outlook 上，草稿 ID 不变；在 iCloud/通用 IMAP 上无法就地更新（IMAP 邮件不可变），因此会删除旧草稿并追加一封新草稿：返回的 ID 是一个新 ID，之后务必使用该 ID
email_draft_list	列出所有草稿

整理（8）

工具	描述
email_move	将邮件移至其他文件夹。支持 IMAP/iCloud 的 sourceFolder
email_transfer	在账户之间移动或复制邮件，并通过原始 MIME 传输保留原始邮件（发件人、日期、线程信息）。只有在确认导入成功后，deleteAfter=true 才会将源邮件移至废纸篓（安全的跨账户移动）
email_delete	删除邮件（移至废纸篓或永久删除）。支持 IMAP/iCloud 的 sourceFolder
email_mark	标记为已读/未读、加星标或加旗标。支持 IMAP/iCloud 的 sourceFolder
email_label	添加/移除标签（仅限 Gmail）
email_folder_create	创建新文件夹
email_get_labels	列出所有标签及其数量（仅限 Gmail）
email_get_categories	列出所有类别（仅限 Outlook）

批量操作（4）

工具	描述
email_batch_delete	一次删除多封邮件（Gmail 最多 1000 封，Outlook 每批 20 封，IMAP 使用 UID 范围）
email_batch_move	在一次调用中将多封邮件移至某个文件夹
email_batch_mark	一次将多封邮件标记为已读/未读、加星标或加旗标
email_batch_label	一次为多封邮件添加或移除标签（Gmail 使用原生批量调用，其他服务逐封处理）

所有批量工具都接受 sourceFolder 参数，用于 IMAP/iCloud，并包含顺序执行的回退方案，以实现最大兼容性。

垃圾邮件审核（5）

工具	描述
email_report_spam	将邮件举报为垃圾邮件/垃圾内容，从而训练服务提供商自身的过滤器——这与 Gmail/Outlook 中“举报垃圾邮件”按钮发送的信号相同。这与 email_delete 不同：后者会移除邮件，但不会为过滤器提供训练信息。这不是向服务提供商安全团队提交的滥用举报；它只会训练此账户的过滤器
email_batch_report_spam	一次将多封邮件举报为垃圾邮件/垃圾内容
email_create_block_rule	创建一条长期生效的规则，用于拦截匹配某种模式（发件人域名/地址、主题或任意标头内容）的后续邮件，并将其删除或移走。使用 headerContains（例如，Reply-To 域名）可拦截某类垃圾邮件模板：这类模板的可见“From”域名会轮换，直接匹配不断变化的域名几天后就会失效。iCloud/通用 IMAP 不支持（IMAP 服务器之间没有标准的服务器端规则机制）。在 Outlook 上，moveToJunk 会将邮件直接移至“垃圾邮件”文件夹，并要求 MailboxSettings.ReadWrite 范围。在 Gmail 上，moveToJunk 会跳过收件箱（归档邮件），而不会将邮件实际移至“垃圾邮件”文件夹——Gmail 的过滤器 API 不允许长期规则应用 SPAM 标签（只有 Gmail 自身的分类器可以应用；email_report_spam 仍然可以，因为它是直接对单封邮件执行操作，而不是过滤器）——并且要求 gmail.settings.basic 范围。在这些范围生效前完成身份验证的账户，需要重新运行一次设置向导以再次授予权限
email_list_block_rules	列出账户上的长期拦截规则，供审计或在删除规则前查看
email_delete_block_rule	删除一条长期拦截规则——用于撤销后来发现范围过广的规则

规则工具仅适用于 Gmail 和 Outlook；email_report_spam/email_batch_report_spam 适用于所有服务提供商（iCloud/IMAP 会尽力将邮件移至账户中标记为垃圾邮件的文件夹，但通用 IMAP 没有可供训练的服务商机器学习信号）。

转发规则（3）

工具	描述
email_create_forward_rule	创建一条长期生效的规则，将符合条件（发件人域名/地址、主题或标头内容）的后续邮件转发到另一个地址，例如将供应商发票转发到记账地址。除非 keepInInbox 为 false，否则原邮件会保留在收件箱中。重复创建同一规则时会返回现有规则
email_list_forward_rules	列出账号中所有将邮件转发到其他位置的规则，包括在 Gmail 或 Outlook 中手动创建的规则：审查邮件转发去向
email_delete_forward_rule	按 ID 删除一条转发规则

仅支持 Gmail 和 Outlook。iCloud 和通用 IMAP 没有服务器端规则机制；请在相应服务提供商自己的设置中设置规则。

默认关闭邮件转发，除非你明确允许目标地址。 长期生效的转发规则会将后续邮件副本转出邮箱，而读取邮件的助手可能会根据它读取的邮件收到创建此类规则的请求。因此，email_create_forward_rule 只接受你在服务器环境的 EMAIL_MCP_FORWARD_ALLOWLIST 中自行列出的地址（以逗号分隔）。没有任何工具能修改此列表：

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"],
      "env": { "EMAIL_MCP_FORWARD_ALLOWLIST": "[email protected]" }
    }
  }
}

在 Gmail 中，目标地址还必须是账号的转发地址：在 Gmail 设置中打开“转发和 POP/IMAP”，选择“添加转发地址”，并确认 Google 发送到该地址的邮件。Outlook 无需此步骤，因此才需要允许列表。在屏蔽规则工具推出之前完成身份验证的 Outlook 账号，需要像使用这些工具一样，再运行一次设置向导。

在 Claude Code 中使用

将以下内容添加到 .mcp.json 文件中（项目级或全局 ~/.claude/.mcp.json）：

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}

配置完成后，你可以让 Claude 处理邮件：

• “检查我的收件箱中有哪些未读邮件”
• “搜索上周来自 [email protected] 的邮件”
• “回复 Bob 的最新邮件并感谢他”
• “将所有新闻邮件移到 Archive 文件夹”
• “删除所有垃圾邮件”（使用批量操作以提高速度）
• “起草一封关于会议的后续邮件发给团队”

开发

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode (watch for changes)
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run integration tests (requires real email accounts)
pnpm test:integration

凭据存储

账号凭据使用 AES-256-GCM 加密后存储在 ~/.email-mcp/credentials.enc 中。

默认情况下，加密密钥由稳定且特定于设备的标识符派生（macOS 上为硬件 UUID，Linux 上为 /etc/machine-id，Windows 上为 MachineGuid）；如果这些标识符都不可用，则使用主机名。

你可以设置 EMAIL_MCP_KEY 环境变量以使用自己的口令。 当设备标识符可能发生变化（例如在容器或 CI 环境中），或者你想在不同设备间迁移 credentials.enc 时，建议这样做：

export EMAIL_MCP_KEY="your-strong-passphrase"

设置 EMAIL_MCP_KEY 后，现有凭据文件会在下次读取时自动使用该口令重新加密。

Outlook 刷新令牌保存在 Microsoft 身份验证库（MSAL）的令牌缓存中，即 ~/.email-mcp/msal-cache.enc。该文件使用与 credentials.enc 相同的加密方案和密钥派生方式加密，因此 EMAIL_MCP_KEY 会保护这两个文件。1.8.0 之前的版本将此缓存以纯 JSON 格式保存在 ~/.email-mcp/msal-cache.json 中；1.8.0 会在首次读取时加密缓存并删除明文文件，不会让你退出登录。之后若改用较旧版本，则需要重新登录 Outlook。

在 macOS 和 Linux 上，使用 email_save_attachment 保存的附件仅限所有者访问（0600），email-mcp 为其创建的文件夹权限为 0700。附件不会加密。

email-mcp-setup 启动的 OAuth 登录回调仅监听环回地址（127.0.0.1，以及可用时的 ::1），因此网络上的其他设备无法访问它。

支持

email-mcp 免费使用，且没有付费套餐。它唯一的固定成本是 Google 每年要求为共享 Gmail 登录进行的独立安全评估（CASA，Cloud Application Security Assessment）：每年 675 美元。这是 Google 允许所有人使用一键式 Gmail 设置之前最后一项尚未完成的工作。捐款将持续收取，直到 2026 年 11 月 2 日，也就是评估必须启动的日期；届时维护者会补足差额。进度显示在 email.lumitra.co。

• GitHub Sponsors
• Buy Me a Coffee

许可证

MIT