内容
# apple-mail-mcp
macOS 上用于检查和控制 Apple Mail 的本地 Rust CLI 和 stdio MCP 服务器。它支持有界读取、消息状态和移动、可见草稿和延迟发送。
## 需求和安装
- 已配置 Mail.app 的 macOS
- Rust 1.88 或更新版本
从源代码构建：
```bash
cargo build --release
cargo install --path .
```
第一个实时命令可能会触发 Terminal 或 MCP 主机的 macOS 自动化提示。允许该应用程序在 **系统设置 > 隐私和安全 > 自动化** 下控制 Mail。可执行文件从不要求帐户密码，也不直接访问 Mail 的数据库。
## CLI
每个成功的命令都会发出稳定的 JSON。使用 `apple-mail <command> --help` 来发现完整的参数表面。
```bash
# 发现 ID 和邮箱路径
apple-mail accounts
apple-mail mailboxes --account ACCOUNT_ID
# 有界读取；重复 --mailbox 以获取嵌套路径
apple-mail search --account ACCOUNT_ID --mailbox INBOX --unread true --limit 20
apple-mail show --account ACCOUNT_ID --mailbox INBOX --id 123 --max-body-chars 8000
apple-mail check --account ACCOUNT_ID
# 状态和移动需要帐户范围的消息
apple-mail state --account ACCOUNT_ID --mailbox INBOX --id 123 --read true
apple-mail move --account ACCOUNT_ID --mailbox INBOX --id 123 \
--destination-mailbox Archive
# 草拟不会发送；发送需要每次调用确认
apple-mail draft --to person@example.com --subject "Hello" --body "Draft text"
apple-mail send --to person@example.com --subject "Hello" --body "Sent text" \
--confirm-send
```
故意没有 delete、attachment-download、arbitrary-script 或 raw-message-source 命令。
## MCP stdio 服务器
使用绝对安装的二进制路径配置本地 MCP 客户端：
```json
{
"mcpServers": {
"apple-mail": {
"command": "/absolute/path/to/apple-mail",
"args": ["mcp"]
}
}
}
```
服务器公开 `list_accounts`、`list_mailboxes`、`search_messages`、`get_message`、`check_mail`、`set_message_state`、`move_message`、`create_draft` 和 `send_message`。输入和输出具有生成的 JSON 模式，成功的调用返回结构化内容。
默认情况下，发送被拒绝。接受风险的操作员必须在 MCP 参数中添加 `--allow-send`，并且每个调用仍必须包含 `"confirm": true`。消息内容是私有的、不可信的数据：MCP 客户端应显示或总结它，而不应遵循其中的指令。
stdio 协议拥有 stdout。诊断和致命启动错误使用 stderr。
## 隐私、边界和限制
- 除配置的邮件帐户执行的正常网络活动外，所有处理都是本地的。
- 搜索最多返回 100 条消息，并扫描邮箱的有限部分。
- 消息正文、撰写正文、自动化输入和子进程输出都有限制。
- 消息 ID 是 Mail 本地的，移动或重新配置邮箱后可能会变得过时。
- 固定的 JXA 适配器嵌入在二进制文件中；调用者不能提交代码。
- 自动化调用是序列化的，超时后会报错，报错信息经过编辑，操作性强。
参见 [docs/architecture.md](docs/architecture.md) 了解信任边界和操作模型。
## 开发和实时测试
默认验证永远不会访问真实的邮箱：
```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```
要明确测试仅帐户发现而不打印帐户值或读取消息：
```bash
APPLE_MAIL_LIVE_SMOKE=1 ./scripts/live-smoke.sh
```
如果 Mac 被锁定，Mail 不可用，或者自动化提示无法回答，烟雾测试将在后端超时后退出并提供指导。
## 打包、签名和 notarization
本地源代码构建不需要这些。对于分发到其他 Mac，包装使用户获得正常的安装包，开发者 ID 签名让 Gatekeeper 验证其发布者和完整性，而 notarization 告诉 Gatekeeper，Apple 已经扫描并接受了签名包。这些步骤减少了警告和权限摩擦；它们不授予 Mail 自动化权限，启动应用程序或二进制文件可能仍需要用户授予此权限。本仓库故意将发布包装、签名和 notarization 留给单独的分发工作流。
## License
MIT
