MCP Server Email (Boutquin)

mcp服务器电子邮件

    

快速开始

1. 安装

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

1. 创建配置文件 (~/.config/mcp-email/accounts.json)

对于知名提供商（Gmail、Outlook、Yahoo、iCloud、Fastmail、Zoho），主机和端口会从电子邮件域中自动检测到——只需提供凭据：

   [
     {
       "id": "hello",
       "email": "hello@gmail.com",
       "username": "hello@gmail.com",
       "password": "app-password-here"
     }
   ]

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

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

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

1. 添加到克劳德代码 (~/.claude.json)

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

1. 重新启动Claude代码 --the email_* 工具现在可用。

安装

Go安装（推荐给Go开发人员）

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

自制（macOS/Linux）

brew install boutquin/tap/mcp-server-email

二进制下载

从下载适用于您平台的预构建二进制文件 .

适用于：Linux（amd64、arm64）、macOS（amd64arm64）和Windows（amd64/arm64）。

码头工人

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

MCP捆绑包（克劳德桌面版）

下载 .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_ACCOUNTS 优先。

帐户JSON模式

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

\*对于知名提供商，会自动检测主机和端口（见下文）。自定义服务器需要。 \*\*使用OAuth2身份验证时不需要。

提供商自动检测

当 imap_host/smtp_host 如果省略，服务器将检测电子邮件域中的设置：

配置中的显式主机/端口始终优先于自动检测。

TLS模式

从端口自动检测TLS模式：

覆盖 "use_starttls": true 或 "use_starttls": false 在account对象中。省略自动检测（推荐）。

OAuth2身份验证

对于支持它的提供商（Gmail、Outlook），您可以使用OAuth2而不是应用程序密码。这使用设备代码流（RFC 8628）——不需要浏览器重定向。

1. 创建OAuth2凭据 在提供商的开发人员控制台（谷歌云控制台或Azure AD）中

1. 配置帐户 随着 auth_method: "oauth2":

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

1. 首次连接时，服务器启动设备代码流——将验证URL和代码打印到stderr。访问URL并输入代码进行授权。

1. 令牌被持久化 在 ~/.config/mcp-email/tokens/ 并自动刷新。后续连接在没有重新授权的情况下重用存储的令牌。

支持的OAuth2提供程序： Gmail (gmail.com, googlemail.com)以及 展望 (outlook.com, hotmail.com, live.com).

环境变量

\*其中之一 EMAIL_CONFIG_FILE 或 EMAIL_ACCOUNTS 是必需的。

配置文件权限

配置文件包含帐户密码。始终限制访问：

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

工具（22）

帐户和文件夹工具

邮件列表

消息操作

附件和螺纹

发送草稿

全部可选 account params默认为配置的默认帐户。

搜索

email_search 搜索两者 主体与身体 使用IMAP SEARCH OR (SUBJECT "q") (BODY "q").

可选过滤器在身体扫描之前缩小服务器端的候选集：

现有的操作超时（默认为30秒）阻止对大型邮箱进行挂起体搜索。

附件

email_send 和 email_draft_create 接受a attachments 参数——服务器主机上的文件引用数组：

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

限制（默认值）： 每个文件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工具错误返回，并带有结构化代码前缀：

资源

与苹果桥的比较

此服务器和 苹果桥 分享A Email 模型和参数语义(limit, includeBody, folder, query)因此LLM可以与两者互换使用。主要区别：

发展

先决条件

• 转到1.24+
• 戈朗茨皮棉
• 码头工人 （仅用于集成测试）

构建

go build ./...

单元测试

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

单元测试使用模拟实现 imap.Operations 和 smtp.Operations 接口——不需要实时邮件服务器。

基准测试

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

模糊测试

Fuzz使用种子语料库瞄准舰船 testdata/fuzz/ 目录。运行特定目标：

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

棉绒

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

集成测试

集成测试针对真实的邮件服务器执行完整的IMAP/SMTP堆栈。他们被隔离在后面 integration 构建标签和 永远不要跑 在...期间 go test ./....

邮件服务器：Greenmail

测试使用 绿色邮件，一个打包为Docker镜像的轻量级Java邮件服务器。影响运行方式的关键细节：

快速启动（一个命令）

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:password@example.com -Dgreenmail.hostname=0.0.0.0" \
     greenmail/standalone:2.1.0

等待约3秒，让JVM启动。

1. 运行集成测试

   TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \
   TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \
   TEST_EMAIL=test@example.com TEST_PASSWORD=password \
     go test -tags=integration -race -v ./...

1. 拆除 完成后

   docker stop greenmail && docker rm greenmail

测试环境变量

\*如果对应 HOST 变量未设置，则跳过该测试文件的测试并显示消息（未失败）。

测试涵盖哪些内容

互联网消息访问协议 (internal/imap/integration_test.go --7次测试）：

SMTP (internal/smtp/integration_test.go --4次测试）：

故障排除

持续集成

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

覆盖

要生成组合单元+集成覆盖率报告：

# With Greenmail running (see above):
TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \
TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \
TEST_EMAIL=test@example.com 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/SMTP客户端解耦 imap.Operations 和 smtp.Operations 接口，支持使用模拟进行全面的单元测试。

依赖项

此项目使用 go imap v2 （目前为v2.0.0-beta.8）。 v2 API还不稳定-在v2.0.0版本之前可能会发生突破性的变化。 我们确定了确切的版本 go.mod 并在稳定版发布后迅速升级。

许可证

麻省理工学院