Apple Mail MCP

🚀 Apple Mail MCP 服务器

Apple Mail MCP 服务器是一个全面的模型上下文协议（MCP）服务器，它为 AI 助手提供了通过自然语言访问 Apple Mail 的能力。该服务器基于 FastMCP 构建，支持通过 Claude Desktop 或其他 MCP 兼容客户端直接读取、搜索、组织、撰写和管理电子邮件。

✨ 新特性： 现在包含 电子邮件管理专家技能 —— 这是一个全面的 Claude Code 技能，它将教会 Claude 智能的电子邮件管理工作流程和高效策略！

✨ 主要特性

📧 邮件阅读与搜索

• 收件箱概览：仪表板视图，显示未读邮件数量、文件夹结构和最近的邮件。
• 高级搜索：支持多条件搜索（主题、发件人、附件、阅读状态、日期范围）。
• 跨文件夹搜索：可在所有邮箱或特定文件夹中进行搜索。
• 邮件内容：提供完整的邮件内容预览，长度可配置。
• 线程视图：显示所有邮箱中的对话线程。
• 最近邮件：可快速访问每个账户的最新邮件。

📁 邮件组织

• 邮箱管理：列出并导航文件夹层次结构。
• 移动邮件：支持在文件夹之间转移邮件（支持嵌套邮箱）。
• 状态更新：可批量标记邮件为已读/未读、标记/取消标记。
• 垃圾邮件管理：支持软删除、永久删除和清空垃圾邮件。

✉️ 邮件撰写

• 撰写：支持发送新邮件，包括收件人、抄送和密送。
• 回复：可回复邮件（单条回复或全部回复）。
• 转发：支持转发邮件，并可添加自定义消息。
• 草稿管理：可创建、列出、发送和删除草稿。

📎 附件处理

• 列出附件：查看所有附件的名称和大小。
• 保存附件：将特定附件下载到磁盘。

📊 分析与导出

• 统计信息：提供全面的邮件分析（邮件数量、主要发件人、邮箱分布）。
• 导出：可将单封邮件或整个邮箱导出为 TXT/HTML 格式。

🎓 电子邮件管理专家技能

新特性： 本仓库现在包含一个全面的 Claude Code 技能，它将教会 Claude 如何成为一名专业的电子邮件管理助手！

什么是技能？

技能 是 Claude Code 的一个特性，它将专业知识和工作流程打包，不仅教会 Claude 可以使用哪些 MCP 工具，还教会它如何有效地使用这些工具。这就像是为 Claude 配备了一位电子邮件管理的效率顾问。

MCP + 技能 = 智能电子邮件管理

• Apple Mail MCP（本服务器）= 工具（18 个邮件功能）
• 电子邮件管理技能 (skill-email-management/) = 专业知识（工作流程、策略、最佳实践）

它们共同打造了一个既了解功能又知道如何最佳使用这些功能的智能助手。

技能带来的好处

📋 完整的工作流程：

• 零收件箱：实现并保持收件箱为空。
• 每日邮件分类：快速处理邮件（10 - 15 分钟）。
• 文件夹组织：提供结构策略和归档系统。
• 高级搜索：可立即找到任何邮件。
• 批量操作：高效清理和组织邮件。

🧠 专业知识：

• 行业标准的效率方法（如 GTD、零收件箱）。
• 工具编排模式（何时使用何种工具）。
• 安全优先的方法（备份、限制、确认）。
• 根据收件箱状态提供上下文感知的建议。

📚 即用型资源：

• 6 份详细文档（3500 + 行）。
• 可复制粘贴的工作流模板。
• 全面的搜索模式参考。
• 常见场景及解决方案。

安装技能

该技能可与 MCP 一起使用。将其安装到您的 Claude Code 用户范围：

# 克隆此仓库（如果尚未克隆）
git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp

# 将技能安装到用户范围（可在所有项目中使用）
cp -r skill-email-management ~/.claude/skills/email-management

就是这么简单！当您提及电子邮件管理主题时，技能将自动激活。

使用技能

安装完成后，您可以在 Claude 中使用自然语言与 Apple Mail 进行交互：

阅读邮件

显示我的收件箱概览
我有多少封未读邮件？
列出我工作账户的最近邮件
在我的 Gmail 账户中搜索关于“项目更新”的邮件
在我的工作账户的所有文件夹中搜索关于“发票”的邮件
显示关于“会议”的对话线程

组织邮件

将主题包含“发票”的邮件移动到我的存档文件夹
将来自 john@example.com 的所有邮件标记为已读
标记关于“截止日期”的重要邮件
删除来自 newsletter@example.com 的邮件

撰写与回复

回复关于“域名”的邮件，内容为“感谢更新！”
从我的工作账户向 jane@example.com 撰写一封邮件
将关于“会议记录”的邮件转发给 team@example.com
创建一封关于项目状态的草稿邮件给 John

管理附件

列出关于“发票”的邮件中的附件
保存关于“合同”的邮件中的 PDF 附件

分析与导出

显示我过去 30 天的邮件统计信息
将我存档文件夹中的所有邮件导出为 HTML 格式
获取来自 sarah@example.com 的邮件统计信息

📦 安装指南

前提条件

• 已配置 Apple Mail 的 macOS 系统。
• Python 3.7 或更高版本。
• Apple Mail 中至少配置了一个邮件账户。
• Claude Desktop（用于 MCP 捆绑包安装）或任何 MCP 兼容客户端。

选项 1：MCP 捆绑包（.mcpb） - 推荐

最简单的安装方法是使用预构建的 MCP 捆绑包：

1. 从 发布页面 下载最新的 .mcpb 文件。

2. 在 Claude Desktop 中安装：

   • 打开 Claude Desktop 设置。
   • 导航到 开发者 > MCP 服务器。
   • 点击 从文件安装。
   • 选择下载的 .mcpb 文件。
   • 重启 Claude Desktop。

3. 当提示时授予权限：

   • Mail.app 控制权限。
   • 邮件数据访问权限。

选项 2：手动安装

1. 克隆仓库：

git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp

2. 创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate

3. 安装依赖项：

pip install -r requirements.txt

4. 通过添加以下内容到 ~/Library/Application Support/Claude/claude_desktop_config.json 来配置 Claude Desktop：

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/venv/bin/python3",
      "args": [
        "/path/to/apple-mail-mcp/apple_mail_mcp.py"
      ]
    }
  }
}

5. 重启 Claude Desktop。

构建自己的 .mcpb 捆绑包

要构建可分发的 MCP 捆绑包：

cd apple-mail-mcpb
./build-mcpb.sh

该脚本将在父目录中创建 apple-mail-mcp-v{版本号}.mcpb 文件。

💻 使用示例

基础用法

安装完成后，您可以在 Claude 中使用自然语言与 Apple Mail 进行交互：

# 阅读邮件
Show me an overview of my inbox
How many unread emails do I have?
List recent emails from my work account
Search for emails about "project update" in my Gmail account
Search for emails about "invoice" across all folders in my work account
Show me the conversation thread about "meeting"

# 组织邮件
Move emails with "invoice" in the subject to my Archive folder
Mark all emails from john@example.com as read
Flag important emails about "deadline"
Delete emails from newsletter@example.com

# 撰写与回复
Reply to the email about "Domain name" with "Thanks for the update!"
Compose an email to jane@example.com from my work account
Forward the email about "meeting notes" to team@example.com
Create a draft email to John about project status

# 管理附件
List attachments in emails about "invoice"
Save the PDF attachment from the email about "contract"

# 分析与导出
Show me email statistics for the last 30 days
Export all emails from my Archive folder to HTML
Get statistics for emails from sarah@example.com

可用工具

MCP 服务器提供 20 个工具：

工具	描述
get_inbox_overview	包含未读邮件数量、文件夹和最近邮件的综合仪表板
list_inbox_emails	列出收件箱中的邮件，并支持过滤选项
get_email_with_content	搜索邮件并提供完整内容预览
search_emails	支持多条件的高级搜索
get_unread_count	快速获取每个账户的未读邮件数量
list_accounts	列出所有配置的邮件账户
get_recent_emails	获取特定账户的最近邮件
list_mailboxes	列出文件夹结构和邮件数量
move_email	在文件夹之间移动邮件
reply_to_email	回复邮件
compose_email	发送新邮件
forward_email	转发邮件
update_email_status	更新邮件状态（已读/未读、标记/取消标记）
manage_trash	管理垃圾邮件（软删除、永久删除、清空垃圾）
get_email_thread	查看对话线程
manage_drafts	管理草稿邮件（创建、列出、发送、删除）
list_email_attachments	列出附件
save_email_attachment	保存附件
get_statistics	获取邮件统计信息
export_emails	导出邮件为 TXT/HTML 格式

配置

电子邮件偏好设置（可选）

您可以配置个人电子邮件偏好设置，在使用邮件工具时，这些设置将提供给 AI 助手。这有助于 Claude 了解您偏好的邮件账户、默认设置和工作流程。

MCP 捆绑包安装（.mcpb）：

通过 .mcpb 捆绑包安装时，您可以在 Claude Desktop 中设置偏好：

1. 打开 Claude Desktop 设置。
2. 导航到 开发者 > MCP 服务器。
3. 点击 Apple Mail MCP 服务器。
4. 配置 电子邮件偏好设置 字段。

示例偏好设置：

Default to BCG account, show max 50 emails, prefer Archive and Projects folders

手动安装：

在 claude_desktop_config.json 中添加 env 部分：

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/apple_mail_mcp.py"],
      "env": {
        "USER_EMAIL_PREFERENCES": "Default to BCG account, show max 50 emails, prefer Archive and Projects folders"
      }
    }
  }
}

偏好设置包含内容：

• 默认邮件账户名称（例如，“BCG”、“Gmail”、“个人”）。
• 首选的最大邮件结果数量。
• 常用的邮箱/文件夹。
• 任何工作流程偏好。

这些偏好设置将自动注入到每个工具的描述中，帮助 Claude 做出更符合您工作流程的决策。

安全限制

一些操作包含安全限制，以防止意外的批量操作：

• update_email_status：默认最大更新数量为 10。
• manage_trash：默认最大删除数量为 5。
• move_email：默认最大移动数量为 1。

如有需要，可通过函数参数调整这些限制。

权限

首次使用时，macOS 会提示您授予权限：

1. Mail.app 控制权限：自动化 Mail 操作所需。
2. 邮件数据访问权限：读取邮件内容所需。

在 系统设置 > 隐私与安全 > 自动化 中授予这两个权限，以确保功能完整。

🔧 技术细节

• 框架：FastMCP - Python MCP 服务器框架。
• 自动化：使用 AppleScript 与 Mail.app 进行交互。
• 平台：仅支持 macOS（需要 Apple Mail）。
• Python：3.7+

项目结构

apple-mail-mcp/
├── apple_mail_mcp.py              # 主 MCP 服务器
├── requirements.txt               # Python 依赖项
├── README.md                      # 本文件
├── LICENSE                        # MIT 许可证
├── CHANGELOG.md                   # 版本历史
├── claude_desktop_config_example.json  # 配置示例
├── apple-mail-mcpb/
│   ├── manifest.json              # MCP 捆绑包元数据
│   └── build-mcpb.sh             # 捆绑包构建脚本
└── skill-email-management/        # 🎓 电子邮件管理专家技能
    ├── README.md                  # 技能安装与使用指南
    ├── SKILL.md                   # 核心工作流程与专业知识
    ├── examples/                  # 工作流程示例
    │   ├── inbox-zero-workflow.md
    │   ├── email-triage.md
    │   └── folder-organization.md
    └── templates/                 # 可重复使用的模式
        ├── common-workflows.md
        └── search-patterns.md

故障排除

Mail.app 无响应

• 确保 Mail.app 正在运行。
• 检查系统设置中是否已授予权限。
• 重启 Mail.app 和 Claude Desktop。

性能缓慢

• 获取邮件内容比获取元数据慢。
• 不需要内容预览时，使用 include_content: false。
• 对于大型搜索，减少 max_results。

未找到邮箱

• 使用 Mail.app 中显示的准确文件夹名称。
• 对于嵌套文件夹，使用 / 分隔符："Projects/Amplify Impact"。
• 某些账户（如 Exchange）可能使用不同的邮箱名称。

权限错误

# 通过系统设置授予权限
System Settings > Privacy & Security > Automation > [Your Terminal/Claude]

贡献

欢迎贡献代码！请随时提交拉取请求。对于重大更改：

1. 分叉仓库。
2. 创建功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开拉取请求。

路线图

近期新增功能：

• [x] ✨ 包含工作流程和最佳实践的电子邮件管理专家技能（v1.0.0）

未来考虑的增强功能：

• [ ] 智能邮箱支持
• [ ] 规则/过滤器管理
• [ ] 电子邮件模板系统
• [ ] 批量操作改进
• [ ] 增强搜索运算符
• [ ] 多账户操作

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 基于 Jeremiah Lowin 的 FastMCP 构建。
• 受 模型上下文协议 规范启发。
• 感谢 Anthropic 提供的 Claude Desktop、MCP 支持和 Claude Code 技能。
• 电子邮件管理专家技能展示了将 MCP 与技能相结合的最佳实践。

支持

• 问题反馈：GitHub 问题
• 讨论：GitHub 讨论

变更日志

请参阅 CHANGELOG.md 了解版本历史和发布说明。

---

为 Claude Desktop 社区精心打造 ❤️