MCP Icloud Email

Icloud电子邮件MCP服务器

A. 模型上下文协议 该服务器允许AI助手通过IMAP和SMTP完全访问Apple iCloud Mail。搜索、阅读、发送、回复、组织和管理您的iCloud邮箱——所有这些都可以从Claude或任何兼容MCP的客户端完成。

用Go和the mcp-go SDK。作为Linux、macOS和Windows的单个静态二进制文件发布。

______________________________________________________________________

目录

• 特性
• 快速开始
• 先决条件
• 安装
• 配置
• 使用Claude Desktop
• 可用工具
• 使用大型收件箱
• 发展
• 建筑
• 安全
• 故障排除
• 贡献
• 许可证

______________________________________________________________________

特性

电子邮件操作

• 使用日期范围、阅读状态和文本查询过滤器搜索和列出电子邮件
• 检索完整的电子邮件内容，包括正文、标题和附件元数据
• 发送支持CC、BCC和HTML的新电子邮件
• 回复电子邮件，回复所有支持
• 发送前保存草稿以供审阅
• 按文件名下载附件（到磁盘或以base64格式）

邮箱管理

• 列出、创建和删除邮箱文件夹（包括嵌套文件夹）
• 在文件夹之间移动电子邮件
• 将电子邮件标记为已读或未读
• 用可定制的颜色标记电子邮件以进行跟进
• 删除电子邮件（移至垃圾箱或永久）
• 在不获取内容的情况下计数匹配过滤器的电子邮件

可操作的

• 具有互斥保护的线程安全IMAP访问
• 具有UUID请求相关性的结构化JSON日志记录
• 每次工具调用时60秒超时中间件
• 输入验证：防止路径遍历、大小限制、文件夹/ID清理
• 用于客户端安全的MCP工具注释（只读、破坏性、幂等）
• 具有测试、linting和漏洞扫描的CI管道

______________________________________________________________________

快速开始

# Install
go install github.com/rgabriel/mcp-icloud-email@latest

# Set credentials (app-specific password, not your main iCloud password)
export ICLOUD_EMAIL="you@icloud.com"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"

# Run
mcp-icloud-email

或者从以下网址下载预构建的二进制文件 发布 页面。

______________________________________________________________________

先决条件

• 转到1.21+ -- 安装 （仅在从源构建时需要）
• Icloud帐户 启用了双因素身份验证
• 应用程序特定密码 --IMAP/SMTP访问所需

生成特定于应用程序的密码

1. 首选 appleid.apple.com 并登录
2. 导航到 登录和安全 > 应用程序特定密码
3. 点击 生成特定于应用程序的密码
4. 输入标签（例如“MCP电子邮件服务器”）并单击 创建
5. 复制生成的密码(xxxx-xxxx-xxxx-xxxx)并安全地存放

笔记：

• 您的Apple ID必须启用双因素身份验证
• 您最多可以创建25个活动应用程序特定密码
• 更改您的主Apple ID密码会撤销所有特定于应用程序的密码
• 切勿使用iCloud主密码访问IMAP/SMTP

______________________________________________________________________

安装

来源

git clone https://github.com/rgabriel/mcp-icloud-email.git
cd mcp-icloud-email
make build

使用 go install

go install github.com/rgabriel/mcp-icloud-email@latest

码头工人

docker build -t mcp-icloud-email .

docker run \
  -e ICLOUD_EMAIL="you@icloud.com" \
  -e ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
  mcp-icloud-email

Docker镜像使用多阶段构建 无发行版 基本映像，并以非root用户身份运行。

预构建二进制文件

从以下网址下载适用于您平台的二进制文件 发布 页面。二进制文件可用于：

SHA256校验和与每个二进制一起提供。

______________________________________________________________________

配置

服务器需要两个环境变量：

您可以将这些设置为环境变量，也可以将它们放置在 .env 文件：

cp .env.example .env
# Edit .env with your credentials

______________________________________________________________________

使用Claude Desktop

将服务器添加到Claude Desktop配置文件中。

macOS -- ~/Library/Application Support/Claude/claude_desktop_config.json

Linux -- ~/.config/claude/claude_desktop_config.json

视窗 -- %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "icloud-email": {
      "command": "/path/to/mcp-icloud-email",
      "env": {
        "ICLOUD_EMAIL": "you@icloud.com",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

保存后重新启动Claude Desktop。

______________________________________________________________________

可用工具

服务器公开了14个MCP工具。每个工具都包含模式约束和注释，指示它是只读的、破坏性的还是幂等的。

搜索邮件

使用可选过滤器搜索和列出电子邮件。为了提高效率，返回电子邮件标题（不是全文）。

响应包括 count （返回）， total （在偏移/限制之前匹配）和一系列电子邮件摘要。

get_email

检索完整的电子邮件内容，包括正文、HTML、标题和附件列表。

send_邮件

撰写并发送一封新电子邮件。

回复_电子邮件

回复现有电子邮件。自动设置“答复”和“引用”标题。

草稿_邮件

将电子邮件另存为草稿。支持带有自动标头线程的回复草稿。

删除电子邮件

通过将电子邮件移至垃圾箱删除，或永久删除。

move_mail

将电子邮件从一个文件夹移动到另一个文件夹。

mark_read

更改电子邮件的已读/未读状态。

flag_mail

用可选颜色标记电子邮件以进行跟进。

集 flag 到 none 删除所有标志。

计数_邮件

在不下载邮件内容的情况下，统计与过滤器匹配的电子邮件。

list_folders

列出所有可用的邮箱文件夹。不接受任何参数。

创建文件夹

创建新的邮箱文件夹。

删除文件夹

删除邮箱文件夹。非空文件夹需要明确确认。

无法删除系统文件夹（收件箱、已发送、回收站）。

获取附件

按文件名下载电子邮件附件。

______________________________________________________________________

使用大型收件箱

服务器使用服务器端的IMAP SEARCH命令，因此在下载任何数据之前，邮件服务器上会进行过滤。默认设置已针对大型邮箱进行了调整：

• search_emails 默认为过去30天，限制为50天
• count_emails 返回计数而不获取消息内容
• get_email 按需加载单个消息的全文内容

推荐工作流程：

1. 使用 count_emails 检查有多少电子邮件符合您的条件
2. 调整 last_days, since/before，或 unread_only 缩小结果
3. 使用 search_emails 随着 offset 和 limit 用于分页
4. 使用 get_email 仅适用于您需要完整阅读的特定消息

______________________________________________________________________

发展

建筑

make build          # Build binary
make test           # Run tests with race detector
make lint           # Run golangci-lint
make vet            # Run go vet
make vuln           # Run govulncheck
make all            # vet + lint + test + build
make docker         # Build Docker image
make tools          # Install dev tools (golangci-lint, govulncheck)

本地运行

export ICLOUD_EMAIL="you@icloud.com"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
make run

测试

该项目包括78多个表驱动测试，涵盖所有工具处理程序、输入验证和错误路径。测试使用模拟实现 EmailService 和 EmailSender 接口——不需要实时IMAP/SMTP连接。

make test

MCP检验员测试

使用 MCP检查员 以交互方式测试服务器：

npx @modelcontextprotocol/inspector mcp-icloud-email

CI管道

每一次推动 main 或 dev 每个pull请求都会运行：

• go vet 和 go test -race --正确性和数据竞争检测
• golangci-lint --静态分析（errcheck、govet、staticcheck、gosec、gocritic等）
• govulncheck --已知漏洞扫描

标签发布(v*.*.*)使用SHA256校验和触发自动跨平台构建。

______________________________________________________________________

建筑

mcp-icloud-email/
  main.go              Server setup, tool registration, middleware chain
  config/config.go     Environment variable loading and validation
  imap/client.go       IMAP client (imap.mail.me.com:993, TLS)
  smtp/client.go       SMTP client (smtp.mail.me.com:587, STARTTLS)
  tools/
    interfaces.go      EmailReader, EmailWriter, EmailService, EmailSender
    helpers.go         Address parsing, shared utilities
    validate.go        Input validation (paths, folders, IDs, sizes)
    handlers_test.go   78+ table-driven tests with mocks
    .go          One file per tool handler (14 files)

中间件链： 每个工具调用都经过 logging -> timeout -> handler日志中间件分配UUID请求ID，并记录工具名称、持续时间和结果。超时中间件强制执行60秒的最后期限。

螺纹安全： IMAP客户端使用 sync.Mutex 以序列化访问。内部方法（小写）假设调用者持有锁，防止嵌套调用造成死锁，如 DeleteEmail -> moveEmail.

依赖项

______________________________________________________________________

安全

• 仅限应用程序特定密码 --从不接受或存储您的主iCloud密码
• TLS无处不在 --端口993上的IMAP（隐式TLS），端口587上的SMTP（STARTTLS）
• 输入验证 --路径遍历防止、空字节拒绝、IMAP通配符过滤、控制字符拒绝、数字UID验证
• 大小限制 --10 MB正文，998个字符的主题（根据RFC 2822）
• 分散Docker镜像 --最小攻击面，以非根模式运行
• 无第三方数据共享 --服务器在本地运行，仅与iCloud服务器通信
• 可撤销访问 --可以随时从appleid.apple.com撤销特定于应用程序的密码

永远不要承诺你的 .env 文件到版本控制。这 .gitignore 已经将其排除在外。

______________________________________________________________________

故障排除

认证失败

• 验证您使用的是特定于应用程序的密码，而不是iCloud主密码
• 检查您的Apple ID是否启用了双因素身份验证
• 在appleid.apple.com重新生成新的应用程序特定密码
• 确认您的电子邮件地址与您的Apple ID匹配

未找到文件夹

• 跑 list_folders 查看您帐户的确切文件夹名称
• iCloud使用“已删除邮件”而不是“垃圾箱”之类的名称
• 文件夹名称区分大小写

日期格式无效

• 使用ISO 8601： 2024-01-15T14:30:00Z
• 如果不是UTC，请包括时区偏移： 2024-01-15T14:30:00-05:00

超时或响应缓慢

• 检查您的互联网连接
• 减少 limit 大型结果集的参数
• 使用 count_emails 在搜索之前首先衡量结果大小
• 使用较窄的日期范围 since/before 或 last_days

未找到电子邮件

• 每个文件夹的电子邮件ID（UID）都是唯一的——请确保您在正确的文件夹中查找
• 自检索ID以来，电子邮件可能已被移动或删除
• 使用 search_emails 查找当前电子邮件ID

______________________________________________________________________

贡献

欢迎捐款。请在提交pull请求之前打开一个问题来讨论更大的更改。

______________________________________________________________________

许可证

MIT许可证——见 许可证 了解详情。