技术文档摘要

Apple Mail MCP 服务器

这是一个全面的模型上下文协议（MCP）服务器，提供人工智能助手通过自然语言访问 Apple Mail 的功能。该服务器使用 FastMCP 构建，允许通过 Claude Desktop 或其他兼容 MCP 的客户端直接读取、搜索、组织、编写和管理电子邮件。

✨ 新功能： 现在包括 邮件管理专家技能 — 这是一个全面的 Claude Code 技能，教授 Claude 智能的邮件管理工作流程和生产力策略！

功能

📧 邮件阅读与搜索

• 收件箱概览：带有未读邮件数量、文件夹结构和最近邮件的仪表板视图
• 高级搜索：多条件搜索（主题、发件人、附件、已读状态、日期范围）
• 跨文件夹搜索：搜索所有邮箱或特定文件夹
• 邮件内容：可配置长度的全文预览
• 会话视图：跨所有邮箱的对话线程
• 最近邮件：快速访问每个账户的最新消息

📁 邮件组织

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

✉️ 邮件撰写

• 撰写：发送新邮件，支持 TO、CC、BCC
• 回复：回复消息（单个回复或全部回复）
• 转发：带可选自定义消息的邮件转发
• 草稿管理：创建、列出、发送和删除草稿

📎 附件处理

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

📊 分析与导出

• 统计：全面的邮件分析（数量、主要发件人、邮箱分布）
• 导出：导出单封邮件或整个邮箱至 TXT/HTML 格式

🎓 邮件管理专家技能

新功能： 本仓库现在包含一个全面的 Claude Code 技能，教授 Claude 如何成为邮件管理方面的专家助手！

技能是什么？

技能 是 Claude Code 的一个特性，它封装了专业知识和工作流程，不仅教会 Claude 它可以做什么（MCP 工具），还教会它如何有效地做到这一点。这就像给 Claude 提供了一个邮件管理的生产力顾问。

MCP + 技能 = 智能邮件管理

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

结合在一起，它们创造了一个既知道能力又知道如何最好地利用这些能力的智能助手。

使用技能获得什么

📋 完整的工作流程：

• 零收件箱 - 达成并维持空收件箱
• 每日邮件分类 - 快速处理邮件（10-15 分钟）
• 文件夹组织 - 结构策略和归档系统
• 高级搜索 - 即时找到任何邮件
• 批量操作 - 清理和组织高效

🧠 专家知识：

• 行业标准的生产力方法（GTD、零收件箱）
• 工具编排模式（何时使用哪个工具）
• 安全第一的方法（备份、限制、确认）
• 基于收件箱状态的上下文感知建议

📚 现成资源：

• 6 份详细文档（超过 3,500 行）
• 可复制粘贴的工作流模板
• 综合搜索模式参考
• 常见场景及解决方案

安装技能

该技能与 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 Code 关于邮件管理：

示例：

• "帮助我实现零收件箱"
• "分类我的收件箱"
• "我应该如何组织项目邮件？"
• "查找所有关于 Alpha 项目的 John 发来的邮件"
• "清理去年的旧邮件"

Claude 将会：

1. ✅ 识别邮件管理请求
2. ✅ 加载专家工作流程和最佳实践
3. ✅ 智能地使用 MCP 工具
4. ✅ 提供可操作的逐步指导

技能内部包含

skill-email-management/
├── SKILL.md                        # 核心工作流程及工具编排
├── examples/
│   ├── inbox-zero-workflow.md     # 完整的零收件箱方法论
│   ├── email-triage.md            # 快速日常分类技巧
│   └── folder-organization.md     # 文件夹结构策略
└── templates/
    ├── common-workflows.md        # 可复制粘贴的工作流模式
    └── search-patterns.md         # 综合搜索参考

📖 阅读完整的技能文档 →

安装前与安装后对比

安装前	安装后
"显示我的邮件"	"让我分析您的收件箱状态，并建议最优工作流程"
单独使用工具	智能编排多步骤工作流程
通用响应	专家生产力策略和上下文感知建议
用户自己决定顺序	预构建的工作流程（零收件箱、GTD、分类等）

💡 小贴士： 技能和 MCP 设计为协同工作。安装两者以获得完整的智能邮件管理体验！

安装

先决条件

• 配置好 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. 配置 Claude Desktop，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "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{version}.mcpb。

使用示例

安装后，您可以使用自然语言在 Claude 中与 Apple Mail 互动：

阅读邮件

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

组织邮件

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

撰写与回复

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

管理附件

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

分析与导出

显示过去 30 天的邮件统计信息
将我的存档文件夹中的所有邮件导出为 HTML
获取来自 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. 配置 邮件偏好设置 字段

示例偏好设置：

默认使用 BCG 账户，最多显示 50 封邮件，优先使用存档和项目文件夹

手动安装：

在您的 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": "默认使用 BCG 账户，最多显示  50 封邮件，优先使用存档和项目文件夹"
      }
    }
  }
}

偏好设置应包括的内容：

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

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

安全限制

多个操作包括安全限制，以防止意外的大批量操作：

• update_email_status：默认最大 10 次更新
• manage_trash：默认最大 5 次删除
• move_email：默认最大 1 次移动

这些限制可以在需要时通过函数参数进行调整。

权限

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

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

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

技术细节

• 框架：FastMCP — Python MCP 服务器框架
• 自动化：用于 Mail.app 交互的 AppleScript
• 平台：仅限 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）可能使用不同的邮箱名称

权限错误

# 通过系统设置授予权限
系统设置 > 隐私与安全性 > 自动化 > [您的终端/Claude]

贡献

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

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

发展路线图

最近新增：

• ✨ 邮件管理专家技能，包含工作流程和最佳实践（v1.0.0）

未来增强考虑：

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

许可证

本项目采用 MIT 许可证 — 详情参见 LICENSE 文件。

致谢

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

支持

• 问题：GitHub 问题
• 讨论：GitHub 讨论

更新日志

参见 CHANGELOG.md 了解版本历史和发行说明。

---

为 Claude Desktop 社区制作 ❤️