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 社區精心打造 ❤️