使用说明
苹果邮件MCP
用于Apple Mail的MCP（模型上下文协议）服务器，使AI助手能够阅读、搜索和组织电子邮件。
特性
- 列出邮件帐户和邮箱
- 创建和重命名邮箱
- 按发件人或主题搜索邮件
- 读取消息内容（单个或批量）
- 在邮箱之间移动邮件
- 设置读取/标记状态
- 所有操作都支持批处理以提高效率
安装
# Clone the repository
git clone https://github.com/yourusername/apple-mail-mcp.git
cd apple-mail-mcp
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install the package
pip install -e .
配置
添加到您的Claude Code MCP设置中(~/.claude.json 或项目设置）：
{
"mcpServers": {
"apple-mail": {
"type": "stdio",
"command": "/path/to/apple-mail-mcp/.venv/bin/python",
"args": ["-m", "apple_mail_mcp.server"]
}
}
}
工具
list_计数
列出在Apple mail中配置的所有邮件帐户。
列表_邮箱
列出特定帐户的邮箱（文件夹）。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | Mail.app中显示的帐户名 |
| include-nested | bool | 包含嵌套邮箱（默认值：true） |
list_消息
使用可选筛选列出邮箱中的邮件。支持通过偏移进行分页。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 邮箱路径（例如“INBOX”） |
| limit | int | 要返回的最大消息数（默认值：50） |
| offset | int | 分页时要跳过的消息数（默认值：0） |
| unread_only | bool | 仅未读邮件（默认值：false） |
| flagged_only | bool | 仅标记消息（默认值：false） |
搜索消息
按发件人和/或主题搜索邮件。支持通过偏移进行分页。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 邮箱路径 |
| sendr_contains | string | 按发件人筛选（可选） |
| subject_contains | string | 按主题筛选（可选） |
| limit | int | 要返回的最大消息数（默认值：50） |
| offset | int | 分页时要跳过的消息数（默认值：0） |
read_消息
阅读一条或多条消息的完整内容。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 邮箱路径 |
| message_ids | list[int] | 要读取的消息ID列表 |
move_消息
将一封或多封邮件移动到另一个邮箱。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 源邮箱路径 |
| message_ids | list[int] | 要移动的邮件ID列表 |
| destination_mailbox | string | 目标邮箱路径 |
返回新的消息ID（移动后ID会更改）。
set_messages_status
为一条或多条消息设置读取和/或标记状态。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 邮箱路径 |
| message_ids | list[int] | 要更新的消息ID列表 |
| read_status | bool | 标记为已读（true）或未读（false） |
| flagged_status | bool | 标志（真）或非标志（假） |
创建邮箱
创建新邮箱（文件夹）。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_name | string | 新邮箱的名称 |
| parent_mailbox | string | 嵌套创建的父邮箱路径（可选） |
重命名邮箱
重命名邮箱。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_name | string | 帐户名 |
| mailbox_path | string | 要重命名的邮箱的路径 |
| new_name | string | 邮箱的新名称 |
例子
搜索和存档新闻通讯
1. search_messages(account="Work", mailbox="INBOX", sender_contains="newsletter")
2. move_messages(account="Work", mailbox="INBOX", message_ids=[...], destination="Archive")
将发件人的所有邮件标记为已读
1. search_messages(account="Personal", mailbox="INBOX", sender_contains="notifications@")
2. set_messages_status(account="Personal", mailbox="INBOX", message_ids=[...], read_status=true)
阅读最近未读的邮件
1. list_messages(account="Work", mailbox="INBOX", limit=10, unread_only=true)
2. read_messages(account="Work", mailbox="INBOX", message_ids=[...])
使用分页处理大型收件箱
# First page (messages 0-49)
list_messages(account="Work", mailbox="INBOX", limit=50, offset=0)
# Second page (messages 50-99)
list_messages(account="Work", mailbox="INBOX", limit=50, offset=50)
# Third page (messages 100-149)
list_messages(account="Work", mailbox="INBOX", limit=50, offset=100)
需求
- 已配置Apple Mail的macOS
- Python 3.10+
- 必须运行Mail.app才能访问AppleScript
许可证
麻省理工学院
