Email (IMAP/SMTP)

mcp-server-email

面向 Model Context Protocol 的多账户电子邮件服务。通过 IMAP/SMTP 为大模型提供完整的电子邮件访问能力——阅读、发送、搜索和整理，并支持连接池、速率限制和重试。它是 apple-bridge（本地 Mail.app 访问）的远程电子邮件对应方案。

快速开始

1. 安装

   go install github.com/boutquin/mcp-server-email/cmd/mcp-server-email@latest
   

2. 创建配置文件（~/.config/mcp-email/accounts.json）

   对于常见服务提供商（Gmail、Outlook、Yahoo、iCloud、Fastmail、Zoho），系统会根据电子邮件域名自动检测主机和端口——只需提供凭据：

   [
     {
       "id": "hello",
       "email": "[email protected]",
       "username": "[email protected]",
       "password": "app-password-here"
     }
   ]
   

   对于自定义邮件服务器，请显式指定主机和端口：

   [
     {
       "id": "work",
       "email": "[email protected]",
       "imap_host": "mail.example.com",
       "imap_port": 993,
       "smtp_host": "mail.example.com",
       "smtp_port": 465,
       "username": "[email protected]",
       "password": "app-password-here"
     }
   ]
   

   chmod 600 ~/.config/mcp-email/accounts.json
   

3. 添加到 Claude Code（~/.claude.json）

   {
     "mcpServers": {
       "email": {
         "command": "mcp-server-email",
         "env": {
           "EMAIL_CONFIG_FILE": "~/.config/mcp-email/accounts.json"
         }
       }
     }
   }
   

4. 重启 Claude Code——现在即可使用 email_* 工具。

安装

Go Install（推荐 Go 开发者使用）

go install github.com/boutquin/mcp-server-email/cmd/mcp-server-email@latest

Homebrew（macOS/Linux）

brew install boutquin/tap/mcp-server-email

下载二进制文件

从 GitHub Releases 下载适用于你平台的预构建二进制文件。

支持平台：Linux（amd64、arm64）、macOS（amd64、arm64）、Windows（amd64、arm64）。

Docker

docker run --rm \
  -e EMAIL_ACCOUNTS='[{"id":"main","email":"[email protected]","imap_host":"mail.example.com","imap_port":993,"smtp_host":"mail.example.com","smtp_port":465,"username":"[email protected]","password":"app-password"}]' \
  ghcr.io/boutquin/mcp-server-email:latest

MCP Bundle（Claude Desktop）

从 Releases 下载 .mcpb 文件，并在 Claude Desktop 中打开。

从源代码构建

git clone https://github.com/boutquin/mcp-server-email.git
cd mcp-server-email
go build -o mcp-server-email ./cmd/mcp-server-email

配置

账户在启动时加载一次。更改配置后需要重启服务。

配置文件与环境变量

方式	适用场景
EMAIL_CONFIG_FILE — JSON 文件的路径	生产环境。可通过文件权限锁定（chmod 600）
EMAIL_ACCOUNTS — 环境变量中的内嵌 JSON	测试、CI 或容器化部署

如果两者都已设置，EMAIL_ACCOUNTS 优先。

账户 JSON 架构

[
  {
    "id": "hello",
    "email": "[email protected]",
    "imap_host": "mail.example.com",
    "imap_port": 993,
    "smtp_host": "mail.example.com",
    "smtp_port": 465,
    "username": "[email protected]",
    "password": "app-password-here"
  }
]

字段	必填	描述
id	是	唯一账户标识符
email	是	电子邮件地址
imap_host	否*	IMAP 服务主机名
imap_port	否*	IMAP 端口（993 = 隐式 TLS，143 = STARTTLS）
smtp_host	否*	SMTP 服务主机名
smtp_port	否*	SMTP 端口（465 = 隐式 TLS，587 = STARTTLS）
username	是	登录用户名
password	是**	应用专用密码或账户密码
use_starttls	否	覆盖 TLS 自动检测（true/false）
insecure_skip_verify	否	跳过 TLS 证书验证（开发/测试）
auth_method	否	"password"（默认）或 "oauth2"
oauth_client_id	否	OAuth2 客户端 ID（当 auth_method 为 "oauth2" 时必填）
oauth_client_secret	否	OAuth2 客户端密钥
oauth_token_file	否	覆盖令牌文件路径

*常见服务提供商的主机和端口会自动检测（见下文）。自定义服务器必须填写。 **使用 OAuth2 身份验证时不需要。

提供商自动检测

省略 imap_host/smtp_host 时，服务会根据电子邮件域名检测设置：

提供商	域名	IMAP	SMTP
Gmail	gmail.com、googlemail.com	imap.gmail.com:993	smtp.gmail.com:587
Outlook	outlook.com、hotmail.com、live.com	outlook.office365.com:993	smtp.office365.com:587
Yahoo	yahoo.com	imap.mail.yahoo.com:993	smtp.mail.yahoo.com:587
iCloud	icloud.com、me.com、mac.com	imap.mail.me.com:993	smtp.mail.me.com:587
Fastmail	fastmail.com、fastmail.fm	imap.fastmail.com:993	smtp.fastmail.com:587
Zoho	zoho.com、zohomail.com	imap.zoho.com:993	smtp.zoho.com:587

配置中明确指定的主机/端口始终优先于自动检测。

TLS 模式

TLS 模式会根据端口自动检测：

端口	协议	模式
993	IMAP	隐式 TLS
143	IMAP	STARTTLS
465	SMTP	隐式 TLS
587	SMTP	STARTTLS

在账户对象中设置 "use_starttls": true 或 "use_starttls": false 可覆盖此设置。省略该项则自动检测（推荐）。

OAuth2 身份验证

对于支持 OAuth2 的提供商（Gmail、Outlook），可以使用 OAuth2 代替应用专用密码。此方式采用设备码流程（RFC 8628），无需浏览器重定向。

1. 在提供商的开发者控制台中创建 OAuth2 凭据（Google Cloud Console 或 Azure AD）

2. 使用 auth_method: "oauth2" 配置账户：

   [
     {
       "id": "gmail",
       "email": "[email protected]",
       "username": "[email protected]",
       "auth_method": "oauth2",
       "oauth_client_id": "your-client-id.apps.googleusercontent.com",
       "oauth_client_secret": "your-client-secret"
     }
   ]
   

3. 首次连接时，服务会启动设备码流程，并将验证 URL 和代码打印到 stderr。访问该 URL 并输入代码以完成授权。

4. 令牌会保存在 ~/.config/mcp-email/tokens/ 中，并自动刷新。后续连接会复用已存储的令牌，无需重新授权。

支持 OAuth2 的提供商：Gmail（gmail.com、googlemail.com）和 Outlook（outlook.com、hotmail.com、live.com）。

环境变量

变量	必填	默认值	说明
EMAIL_CONFIG_FILE	是*	—	JSON 配置文件的路径
EMAIL_ACCOUNTS	是*	—	账户配置的 JSON 数组（内联）
EMAIL_DEFAULT_ACCOUNT	否	第一个账户	默认账户 ID
EMAIL_IMAP_TIMEOUT_MS	否	30000	IMAP 操作超时时间（毫秒）
EMAIL_SMTP_TIMEOUT_MS	否	30000	SMTP 操作超时时间（毫秒）
EMAIL_IMAP_RATE_LIMIT	否	60	每个账户每分钟的 IMAP 请求数
EMAIL_SMTP_RATE_LIMIT	否	100	每个账户每小时的 SMTP 发送数
MAX_ATTACHMENT_SIZE_MB	否	18	单个附件的最大大小（MB）
MAX_TOTAL_ATTACHMENT_SIZE_MB	否	18	每封邮件所有附件的最大总大小（MB）
MAX_DOWNLOAD_SIZE_MB	否	25	附件下载的最大大小（MB）
EMAIL_POOL_CLOSE_TIMEOUT_MS	否	5000	连接池关闭超时时间（毫秒）
EMAIL_DEBUG	否	false	将调试日志输出到 stderr
LOG_LEVEL	否	info	日志级别：debug、info、warn、error
LOG_FORMAT	否	json	日志格式：json 或 text

*必须设置 EMAIL_CONFIG_FILE 或 EMAIL_ACCOUNTS 之一。

配置文件权限

配置文件包含账户密码。请始终限制其访问权限：

chmod 600 ~/.config/mcp-email/accounts.json

工具（22）

账户和文件夹工具

工具	说明	关键参数
email_accounts	列出已配置账户及其连接状态	—
email_folders	列出所有文件夹及未读/总数	account?
email_folder_create	创建新文件夹	name、account?

消息列表

工具	描述	关键参数
email_list	列出文件夹中的消息	folder?、limit?、offset?、includeBody?、account?
email_unread	列出未读消息	folder?、limit?、includeBody?、account?
email_search	搜索主题和正文	query、from?、to?、since?、before?、folder?、limit?、includeBody?、account?

消息操作

工具	描述	关键参数
email_get	按 ID 获取完整消息	id
email_read_body	分页读取邮件正文	id、offset?、limit?、format?
email_move	将消息移至文件夹	id、destination
email_copy	将消息复制到文件夹	id、destination
email_delete	删除消息（移至垃圾箱或永久清除）	id、permanent?
email_mark_read	将消息标记为已读/未读	id、read
email_flag	标记/取消标记消息	id、flagged
email_reply	回复消息（设置 In-Reply-To、References，并引用正文）	id、body、all?、cc?、bcc?、isHtml?、account?
email_forward	转发消息（重新附上原始附件）	id、to、body?、cc?、bcc?、isHtml?、account?
email_batch	对多条消息执行批量操作	action、ids、destination?、permanent?、read?、flagged?

附件和会话

工具	描述	关键参数
email_attachment_list	列出消息的附件	id
email_attachment_get	按索引下载附件	id、index、saveTo?
email_thread	获取对话会话（搜索 INBOX、Sent、Archive 和 All Mail）	id

发送和草稿

工具	描述	关键参数
email_send	通过 SMTP 发送邮件，可选添加附件	to、subject、body、cc?、bcc?、replyTo?、isHtml?、attachments?、account?
email_draft_create	保存草稿，可选添加附件	to?、subject?、body?、cc?、bcc?、isHtml?、attachments?、account?
email_draft_send	发送现有草稿	id

所有可选的 account 参数均默认为已配置的默认账户。

搜索

email_search 使用 IMAP SEARCH OR (SUBJECT "q") (BODY "q") 搜索主题和正文。

可选筛选条件会在扫描正文前于服务端缩小候选范围：

筛选条件	格式	示例
from	电子邮件地址或姓名	"[email protected]"
to	电子邮件地址或姓名	"[email protected]"
since	YYYY-MM-DD	"2026-01-01"
before	YYYY-MM-DD	"2026-02-01"

现有的操作超时设置（默认为 30s）可防止大型邮箱中的正文搜索一直卡住。

附件

email_send 和 email_draft_create 接受 attachments 参数——这是一个包含服务主机上文件引用的数组：

{
  "attachments": [
    {"path": "/tmp/report.pdf"},
    {"path": "/tmp/data.csv", "filename": "Q1-data.csv", "content_type": "text/csv"}
  ]
}

参数	必填	描述
path	是	服务主机上的绝对文件路径
filename	否	覆盖显示的文件名（默认为 path 的基本文件名）
content_type	否	MIME 类型（若未指定，则根据文件扩展名自动检测）

**限制（默认值）：**每个文件 18 MB，总计 18 MB（Base64 编码前；编码后仍低于 25 MB 的 SMTP 上限）。可通过 MAX_ATTACHMENT_SIZE_MB 和 MAX_TOTAL_ATTACHMENT_SIZE_MB 环境变量进行配置。

**下载限制：**附件下载（email_attachment_get）默认上限为 25 MB，可通过 MAX_DOWNLOAD_SIZE_MB 配置。

验证失败（文件不存在、路径不是绝对路径、超出大小限制）时，会返回 INVALID_ARGUMENT。

消息 ID

消息 ID 是组合字符串，用于编码账户、邮箱和 UID：

{account}:{mailbox}:{uid}

示例：hello:INBOX:12345

所有 CRUD 工具（email_get、email_move、email_copy、email_delete、email_mark_read、email_flag、email_draft_send）都会从 ID 中提取账户和文件夹，无需单独传递参数。

错误代码

所有错误都会作为 MCP 工具错误返回，并带有结构化代码前缀：

代码	含义
AUTH_FAILED	IMAP/SMTP 身份验证失败
CONNECTION_FAILED	无法连接到服务
ACCOUNT_NOT_FOUND	未知账户 ID
FOLDER_NOT_FOUND	邮箱不存在
MESSAGE_NOT_FOUND	邮箱中找不到该 UID
INVALID_ARGUMENT	缺少或无效的参数（包括附件验证）
TIMEOUT	操作超时
INTERNAL	未预期的服务端错误

资源

URI	描述
email://status	服务版本、账户连接状态、速率限制配置

与 apple-bridge 的比较

此服务与 apple-bridge 共用 Email 模型和参数语义（limit、includeBody、folder、query），因此大模型可以互换使用两者。主要区别如下：

方面	mcp-server-email	apple-bridge
传输方式	IMAP/SMTP（远程）	Mail.app（本地）
工具前缀	email_*	mail_*
消息 ID	{account}:{mailbox}:{uid}	RFC 5322 Message-ID
创建文件夹	支持	不支持（Mail.app 需要通过 UI 操作）
复制消息	支持	不支持
发送草稿	支持	不支持（Mail.app 使用撰写界面）
附件（发送）	服务主机上的文件路径	暂不支持

开发

先决条件

• Go 1.24+
• golangci-lint
• Docker（仅用于集成测试）

构建

go build ./...

单元测试

make test
# or: go test -race -count=1 ./...

单元测试使用 imap.Operations 和 smtp.Operations 接口的模拟实现，无需运行中的邮件服务。

基准测试

go test -bench=. -benchmem ./...

基准测试	包	测量内容
BenchmarkPoolGetRelease	imap	连接池获取/释放周期
BenchmarkExtractAttachments	imap	MIME 附件提取
BenchmarkHtmlToText	tools	HTML 到纯文本的转换
BenchmarkLimiterAllow	retry	速率限制器（顺序执行）
BenchmarkLimiterAllow_Parallel	retry	速率限制器（并发执行）

模糊测试

模糊测试目标在 testdata/fuzz/ 目录中附带种子语料库。运行指定目标：

go test -fuzz=FuzzParseMessageID ./internal/models/ -fuzztime=30s

目标	包	模糊测试内容
FuzzBuildSearchCriteria	imap	IMAP 搜索查询构建器
FuzzExtractAttachmentByIndex	imap	附件索引边界处理
FuzzExtractContentType	imap	MIME 内容类型解析器
FuzzParseMessageID	models	组合消息 ID 编解码器
FuzzHtmlToText	tools	HTML 到文本的净化器
FuzzSplitAddresses	tools	邮件地址列表拆分器

代码检查

make lint
# or: golangci-lint run ./...

集成测试

集成测试会针对真实邮件服务测试完整的 IMAP/SMTP 协议栈。它们通过 integration 构建标签隔离，绝不会在 go test ./... 期间运行。

邮件服务：Greenmail

测试使用 Greenmail，这是一个打包为 Docker 镜像的轻量级 Java 邮件服务。运行测试时需要注意以下关键信息：

设置	值	重要性
IMAPS 端口	3993	Greenmail 的 SSL IMAP 端口（不是 993）。代码会根据端口号自动检测 TLS，因此测试会显式设置 UseStartTLS=false，以便在这个非标准端口上强制使用隐式 TLS。
SMTPS 端口	3465	Greenmail 的 SSL SMTP 端口（不是 465）。同样需要设置 UseStartTLS=false。
绑定地址	0.0.0.0	Greenmail 在容器内默认使用 127.0.0.1，这会导致 Docker 端口映射静默失败（连接返回 EOF）。必须传入 -Dgreenmail.hostname=0.0.0.0。
用户名	test	Greenmail 仅使用本地部分（@ 之前的部分）作为登录用户名，而不是完整的电子邮件地址。如果用户是 [email protected]，IMAP/SMTP 用户名就是 test。
TLS 证书	自签名	Greenmail 会生成自签名证书。测试会在账户配置中设置 InsecureSkipVerify: true 来接受这些证书。

快速开始（一条命令）

make test-integration

这会启动 Greenmail 容器、运行所有集成测试，然后拆除容器，无论测试通过还是失败。

手动逐步操作

如果需要反复运行测试而不必每次都重启容器：

1. 启动 Greenmail

   docker run -d --name greenmail \
     -p 3465:3465 -p 3993:3993 \
     -e "GREENMAIL_OPTS=-Dgreenmail.setup.test.all -Dgreenmail.users=test:[email protected] -Dgreenmail.hostname=0.0.0.0" \
     greenmail/standalone:2.1.0
   

   等待约 3 秒，让 JVM 启动。

2. 运行集成测试

   TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \
   TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \
   [email protected] TEST_PASSWORD=password \
     go test -tags=integration -race -v ./...
   

3. 完成后拆除容器

   docker stop greenmail && docker rm greenmail
   

测试环境变量

变量	必需	默认值	描述
TEST_IMAP_HOST	是*	—	IMAP 服务主机名。未设置时会跳过测试。
TEST_IMAP_PORT	否	3993	IMAPS 端口
TEST_SMTP_HOST	是*	—	SMTP 服务主机名。未设置时会跳过测试。
TEST_SMTP_PORT	否	3465	SMTPS 端口
TEST_EMAIL	否	[email protected]	测试账户的电子邮件地址
TEST_USERNAME	否	TEST_EMAIL 的本地部分	IMAP/SMTP 登录用户名（Greenmail 仅使用本地部分）
TEST_PASSWORD	否	password	账户密码

*如果未设置对应的 HOST 变量，该测试文件中的测试会显示一条消息并跳过，而不会失败。

测试覆盖范围

IMAP（internal/imap/integration_test.go — 7 项测试）：

测试	验证内容
ConnectAndListFolders	TLS 连接、身份验证、文件夹列表，以及 INBOX 是否存在
SendAndListMessages	SMTP 发送 → IMAP 接收往返流程，正文内容匹配
SearchBySubject	按主题字符串执行 IMAP SEARCH
DeleteMessagePermanent	标记为已删除并执行 expunge，验证邮件已消失
MoveMessage	使用 IMAP MOVE 移动到其他文件夹（如果服务不支持 MOVE 扩展则跳过）
DraftWorkflow	SaveDraft → GetDraft → DeleteDraft 生命周期（如果没有 APPENDUID 则跳过）
MarkReadAndFlag	设置已读/已标记标志，并通过 GetMessage 验证

SMTP（internal/smtp/integration_test.go — 4 项测试）：

测试	验证内容
SendPlainText	纯文本邮件投递，通过 IMAP 验证正文内容
SendHTML	HTML 邮件投递，验证 Content-Type 为 text/html
SendWithAttachment	带附件的多部分 MIME，验证元数据中的文件名
RateLimitTokenConsumption	发送操作会消耗速率限制令牌

故障排除

症状	原因	修复方法
连接时出现 EOF 或 connection reset	Greenmail 在容器内绑定到 127.0.0.1	在 GREENMAIL_OPTS 中添加 -Dgreenmail.hostname=0.0.0.0
TLS handshake failure / 证书错误	自签名证书被拒绝	测试配置已设置 InsecureSkipVerify: true——如果编写新测试，也进行相同设置
Invalid login/password	使用了完整的电子邮件地址作为用户名	Greenmail 只接受本地部分（test，而不是 [email protected]）。设置 TEST_USERNAME，或使用默认值。
端口 3993 上出现 STARTTLS 错误	在隐式 TLS 端口上使用了 STARTTLS	测试配置设置了 UseStartTLS=false。不要使用端口 3143/3025（明文，无 TLS）。
测试因“not set”而跳过	未导出 TEST_IMAP_HOST / TEST_SMTP_HOST	导出环境变量，或使用 make test-integration 目标
MoveMessage 测试被跳过	Greenmail 可能不支持 MOVE	预期行为——测试使用了 t.Skip()

CI

集成测试通过 .github/workflows/ci.yml 中的 integration 作业在 GitHub Actions 中自动运行。该作业使用 Greenmail 服务容器，无需手动设置 Docker。具体配置请参阅工作流文件。

覆盖率

要生成单元测试和集成测试的综合覆盖率报告：

# With Greenmail running (see above):
TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \
TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \
[email protected] TEST_PASSWORD=password \
  go test -tags=integration -race -coverprofile=coverage.out ./...

go tool cover -func=coverage.out | tail -1   # total percentage
go tool cover -html=coverage.out             # open in browser

架构

mcp-server-email/
├── cmd/mcp-server-email/     # Entry point
└── internal/
    ├── auth/                 # OAuth2 device code flow, XOAUTH2 SASL, token store
    ├── config/               # Multi-account configuration, provider auto-detection
    ├── imap/                 # IMAP client (split by concern), connection pool, Operations interface
    │   ├── client.go         # Client struct, lifecycle, shared helpers
    │   ├── client_messages.go # List, search, get, attachments
    │   ├── client_folders.go  # Folder ops, role cache
    │   ├── client_drafts.go   # Draft save/get/delete
    │   ├── client_flags.go    # Flags, move, copy, delete
    │   └── pool.go           # Connection pool with configurable close timeout
    ├── log/                  # Structured logging (slog) initialization
    ├── models/               # Email model, message ID codec, error types
    ├── resources/            # email://status resource
    ├── retry/                # Token-bucket rate limiter
    ├── smtp/                 # SMTP client, Operations interface
    └── tools/                # 22 MCP tool handlers + registration

工具处理程序通过 imap.Operations 和 smtp.Operations 接口与 IMAP/SMTP 客户端解耦，从而能够使用模拟对象进行全面的单元测试。

依赖项

本项目使用 go-imap v2（当前版本为 v2.0.0-beta.8）。 v2 API 尚未稳定——在 v2.0.0 发布前可能会发生破坏性变更。 我们在 go.mod 中固定了确切版本，并将在稳定版发布后及时升级。

许可证

MIT