邮件管理服务器

苹果邮件MCP服务器

一个模型上下文协议（MCP）服务器，提供对Apple Mail的编程访问，使Claude等AI助手能够在macOS上阅读、发送、搜索和管理电子邮件。

特性

第1阶段（v0.1.0）-电流

• 🔍 搜索邮件 带过滤器（发件人、主题、阅读状态、日期范围）
• 📧 发送电子邮件 带有确认提示
• 📬 读取消息 包含完整内容和元数据
• 📂 列出邮箱 和文件夹结构
• ✅ 标记为已读/未读

即将推出

• 第2阶段（v0.2.0）：附件、移动消息、标志、线程
• 第3阶段（v0.3.0）：回复/转发、批量操作、模板
• 第4阶段（v0.4.0）：分析、多帐户、高级工作流

安装

先决条件

• macOS 10.15（Catalina）或更高版本
• Python 3.10或更高版本
• Apple Mail已配置至少一个帐户

从 PyPI 安装

pip install apple-mail-mcp

从源代码安装

git clone https://github.com/morgancoopercom/apple-mail-mcp.git
cd apple-mail-mcp
pip install -e ".[dev]"

配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

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

{
  "mcpServers": {
    "apple-mail": {
      "command": "python",
      "args": ["-m", "apple_mail_mcp.server"]
    }
  }
}

权限

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

1. 自动化：允许MCP服务器控制Apple Mail
2. 全磁盘访问 （可选）：仅第4阶段的分析功能需要

用法

配置后，您可以使用自然语言通过Claude Desktop与Apple Mail交互：

例子

搜索电子邮件：

Find all unread emails from john@example.com in the last week

阅读消息：

Show me the content of the most recent email from my manager

发送电子邮件：

Draft an email to alice@example.com thanking her for the meeting

管理文件夹：

List all my mailboxes and show unread counts

标记为已读：

Mark all newsletters from this week as read

可用工具

search_messages

使用各种过滤器搜索邮件。

参数：

• account （必填）：帐户名（例如“Gmail”、“iCloud”）
• mailbox （可选）：邮箱名称（默认：“收件箱”）
• sender_contains （可选）：按发件人电子邮件/域筛选
• subject_contains （可选）：按主题关键字筛选
• read_status （可选）：按已读/未读状态筛选
• date_from （可选）：日期范围的开始日期
• date_to （可选）：日期范围的结束日期
• limit （可选）：返回的最大结果

get_message

获取特定消息的完整详细信息。

参数：

• message_id （必填）：来自搜索结果的邮件ID
• include_content （可选）：包含消息正文（默认值：true）

send_email

通过Apple Mail发送电子邮件。

参数：

• subject （必填）：电子邮件主题
• body （必填）：电子邮件正文（纯文本）
• to （必填）：收件人电子邮件地址列表
• cc （可选）：CC收件人列表
• bcc （可选）：BCC收件人列表

安全： 所有发送操作都需要用户确认。

list_mailboxes

列出帐户的所有邮箱和文件夹。

参数：

• account （必填）：账户名称

mark_as_read

将邮件标记为已读或未读。

参数：

• message_ids （必填）：邮件ID列表
• read （可选）：读为true，未读为false（默认值：true）

安全

此MCP服务器优先考虑安全性和用户控制：

• ✅ 本地执行：所有操作都在您的计算机上本地运行
• ✅ 用户确认：发送电子邮件需要明确批准
• ✅ 输入净化：所有输入都经过验证和转义
• ✅ 审核日志记录：记录操作以提高透明度
• ✅ 无凭据存储：使用现有的Mail.app身份验证
• ✅ 默认情况下为只读：破坏性操作需要确认

攻击面注意事项

将MCP连接器与本地邮件帐户一起使用时：

• 快速注射：恶意电子邮件内容可能会影响人工智能行为
  • 缓解：用户确认敏感操作
• 数据渗漏：克劳德可以访问电子邮件内容
  • 缓解：本地处理，除了Claude API之外没有云同步
• 意外行为：错误可能会导致不必要的操作
  • 缓解：确认提示、速率限制、综合测试

发展

设置开发环境

# Clone repository
git clone https://github.com/morgancoopercom/apple-mail-mcp.git
cd apple-mail-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific test file
pytest tests/unit/test_mail_connector.py

# Run integration tests (requires Mail.app setup)
pytest tests/integration/

代码质量

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

测试驱动开发

本项目全程使用TDD：

1. 先写测试（红色）
2. 实现要传递的最小代码（绿色）
3. 质量重构（重构）
4. 重复

看 测试/ 例如。

建筑

组件

apple-mail-mcp/
├── server.py          # FastMCP server implementation
├── mail_connector.py  # AppleScript interface
├── tools.py           # MCP tool implementations
├── security.py        # Input validation, confirmations
└── utils.py           # Helper functions

运作原理

1. MCP协议：Claude Desktop通过JSON-RPC与服务器通信
2. AppleScript桥：Python通过以下方式执行AppleScript命令 osascript
3. 邮件.app：AppleScript控制Mail.app执行操作
4. 响应：结果作为结构化数据返回给Claude

演出

• 搜索：对于典型邮箱（1000条消息），大约需要1-5秒
• 发送：约1-2秒
• 阅读：每条消息<1秒
• 优化：使用AppleScript whose 高效过滤条款

路线图

• [x] v0.1.0：核心搜索、读取、发送功能
• [ ] v0.2.0版本：附件、移动消息、标志、线程
• [ ] v0.3.0：回复/转发、批量操作、模板
• [ ] v0.4.0：分析、多账户、SQLite集成

看 GitHub问题 详细规划。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 为新功能编写测试
4. 确保所有测试通过(pytest)
5. 提交更改(git commit -m 'Add amazing feature')
6. 推送到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 内置 FastMCP 耶利米·洛因
• 使用Apple Mail的AppleScript界面
• 灵感源自于 MCP协议 通过Anthropic

支持

• 问题: GitHub问题
• 讨论: GitHub讨论
• 文档: docs/

相关项目

• 超级内存/苹果mcp -TypeScript苹果生态系统MCP
• 54年/苹果mcp -Python苹果系统MCP
• 环路/iMCP -Swift原生MCP实现