内容
# Apple-MCPs
适用于 macOS 的原生 Apple MCP 服务器 - 将任何 AI 代理转变为 Siri 应有的功能。
该仓库通过 [模型上下文协议](https://modelcontextprotocol.io)（MCP）提供对核心 Apple 应用程序的直接本地访问。您的 AI 助手可以使用结构化工具来处理您的数据 - 创建提醒，发送消息，查看日历，搜索邮件，管理文件，获取方向 - 同时所有内容都保留在您已经使用的原生应用程序中。
MCP 提供了三个用于处理 Apple 应用程序的基元：
- **工具** - 创建提醒或发送消息等操作
- **资源** - 只读快照，如最近的笔记或今天的提醒
- **提示** - 用于常见任务的可重用工作流，如规划您的日程
所有操作都发生在您的 Mac 上。您的数据保留在 Apple 应用程序中，它们应该属于那里。
## 项目文档
- [变更日志](./CHANGELOG.md)
- [贡献指南](./CONTRIBUTING.md)
- [安全指南](./SECURITY.md)
- [代码模式](./docs/code-mode.md)
- [注意事项](./NOTICE.md)
## 启动文档
- [黄金工作流](./docs/launch/golden-workflows.md)
- [故障模式](./docs/launch/failure-modes.md)
- [兼容性和版本锁定](./docs/launch/compatibility.md)
- [演示脚本](./docs/launch/demo-script.md)
- [检查清单模板提示](./docs/launch/prompts/checklist-template.md)
- [每服务器 E2E 检查清单](./docs/launch/prompts/per-server-e2e-checklist.md)
## 服务器
- [Apple-Tools-MCP](./Apple-Tools-MCP/README.md)，推荐。涵盖 Mail、Calendar、Reminders、Messages、Contacts、Notes、Shortcuts、Files、System 和 Maps 的统一服务器。
- [Apple 文件 MCP](./AppleFiles-MCP/README.md)，用于安全的文件、Finder 邻近工作流和 iCloud Drive 工作流，限于允许的根目录。
- [Apple 系统 MCP](./AppleSystem-MCP/README.md)，用于前台应用程序、电池、剪贴板、真实的专注模式支持元数据、应用程序启动上下文、与助手相关的 macOS 设置读取和写入，以及有限的 GUI 回退自动化。
- [Apple 地图 MCP](./AppleMaps-MCP/README.md)，用于地点搜索、旅行估算和 Apple 地图链接。
- [Apple 邮件 MCP](./AppleMail-MCP/README.md)，仅用于邮件工作流。
- [Apple 日历](./Apple-Calendar-MCP/README.md)，仅用于日历工作流。
- [Apple 提醒事项 MCP](./AppleReminders-MCP/README.md)，用于任务和提醒工作流。
- [Apple 消息 MCP](./AppleMessages-MCP/README.md)，用于 iMessage 和消息工作流。
- [Apple 联系人 MCP](./AppleContacts-MCP/README.md)，用于联系人和收件人解析工作流。
- [Apple 笔记 MCP](./AppleNotes-MCP/README.md)，用于笔记和知识工作流。
- [Apple 快捷方式 MCP](./AppleShortcuts-MCP/README.md)，用于从代理运行 Apple 快捷方式。
## 选择哪一个
**Apple-Tools-MCP**（推荐）- 一个涵盖所有内容的服务器：邮件、日历、提醒事项、消息、联系人、笔记、快捷方式、文件、系统和地图。包括额外的功能，如保存的默认值、每个联系人的路由偏好、线程感知的邮件助手、撤销支持、真实的专注模式上下文、Finder 感知的 文件工作流和 iCloud Drive 感知。
**独立服务器** - 如果您想要更严格的边界或更简单的权限，请选择一个：
- [Apple 文件 MCP](./AppleFiles-MCP/README.md)、[Apple 系统 MCP](./AppleSystem-MCP/README.md)、[Apple 地图 MCP](./AppleMaps-MCP/README.md) 用于专注的工作流
- [Apple 邮件 MCP](./AppleMail-MCP/README.md)、[Apple 日历](./Apple-Calendar-MCP/README.md)、[Apple 提醒事项 MCP](./AppleReminders-MCP/README.md)、[Apple 消息 MCP](./AppleMessages-MCP/README.md)、[Apple 联系人 MCP](./AppleContacts-MCP/README.md)、[Apple 笔记 MCP](./AppleNotes-MCP/README.md)、[Apple 快捷方式 MCP](./AppleShortcuts-MCP/README.md) 用于单一应用程序访问
## 代理路由
使用这些服务器的一些提示：
- `tools/list` 故意保持最小。使用 `search_tools` 发现工具，然后使用 `get_tool_info` 在需要时加载完整的模式和示例。
- 消息某人时，请始终先运行联系人，然后选择消息或邮件。
- 使用邮件线程助手时，用户提到了对话。
- 提醒事项用于到期项目，笔记用于参考资料，日历用于计划时间。
- 当邮件必须从特定身份发送时，请在 `from_account` 中传递确切的发件人电子邮件。
- 代码模式客户端可以使用 `generated/tool_wrappers/python` 中生成的包装器表面，而不是将每个工具模式加载到模型上下文中。
- 有关特定应用程序的详细信息，请参阅独立的 README。
## 基于搜索的发现
发布的 Apple MCP 服务器针对支持搜索的客户端进行了优化：
- `tools/list` 仅公开一个紧凑的始终在线的表面，例如健康检查、权限指导、提示回退、`search_tools` 和 `get_tool_info`
- `search_tools` 按名称、描述、别名和域标签查找延迟工具
- `get_tool_info` 仅在客户端需要时加载延迟工具的完整模式和示例
- 直接 `call_tool` 仍然适用于延迟工具，即使它们不包含在初始 `tools/list` 中
这使得默认上下文更小，同时保留了完整的工具表面。
## 代码模式包装器
仓库还为代码执行客户端提供了生成的工件：
- `generated/tool_catalogs`，每个服务器导出可搜索的工具元数据
- `generated/tool_wrappers/python`，用于延迟工具调用的生成的 Python 包装器
在您想要 Anthropic 样式的代码模式发现和执行，而无需将整个 MCP 表面加载到模型上下文窗口时使用这些。
参见 [docs/code-mode.md](./docs/code-mode.md)，了解包装器布局、客户端接口、结果解析和推荐的工作流。
## 在此 Mac 上安装
<details>
<summary>推荐，安装一体式服务器</summary>
```bash
cd /path/to/Apple-MCPs/Apple-Tools-MCP
./start.sh
```
`start.sh` 在需要时初始化和修复本地虚拟环境，重新安装 `requirements.txt` 更改后的环境，并通过 `stdio` 启动 MCP 服务器。
</details>
<details>
<summary>将所有包安装到一个共享环境中</summary>
```bash
cd /path/to/Apple-MCPs
bash scripts/install_all.sh
```
这会创建一个共享的虚拟环境，并将所有独立的包和 `Apple-Tools-MCP` 安装到其中。当您想要一个可以运行任何服务器而无需依赖 sibling 源路径导入的环境时，请使用此方法。安装的入口点位于 `.venv/bin`，例如 `.venv/bin/apple-tools-mcp`。
</details>
<details>
<summary>安装一个独立的服务器</summary>
示例：
```bash
cd /path/to/Apple-MCPs/AppleMessages-MCP
./start.sh
```
每个服务器文件夹都遵循相同的模式：
- `manifest.json`
- `start.sh`
- `server.py`
- `README.md`
- `src/`
- `tests/`
</details>
## 在 AI 代理中安装
<details>
<summary>通用 MCP 客户端，stdio 配置</summary>
大多数支持本地 `stdio` 服务器的 MCP 客户端可以直接指向服务器的 `start.sh`。
一体式服务器的示例：
```json
{
"mcpServers": {
"apple-tools": {
"command": "/path/to/Apple-MCPs/Apple-Tools-MCP/start.sh",
"args": [],
"env": {
"APPLE_MAIL_MCP_SAFETY_PROFILE": "full_access",
"APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",
"APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage",
"APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
"APPLE_FILES_MCP_SAFETY_MODE": "safe_manage",
"APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage",
"APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage",
"APPLE_NOTES_MCP_SAFETY_MODE": "full_access",
"APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access",
"APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access"
}
}
}
}
```
对于启动质量的助手行为，请使用 [Apple-Tools-MCP/README.md](./Apple-Tools-MCP/README.md) 中所示的助手级安全设置，而不是空的 `env` 块。
独立服务器的示例：
```json
{
"mcpServers": {
"apple-reminders": {
"command": "/path/to/Apple-MCPs/AppleReminders-MCP/start.sh",
"args": [],
"env": {
"APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage"
}
}
}
}
```
</details>
<details>
<summary>Claude 代码示例</summary>
添加一体式服务器：
```bash
claude mcp add --transport stdio --scope project \
apple-tools \
-- /path/to/Apple-MCPs/Apple-Tools-MCP/start.sh
```
添加独立服务器：
```bash
claude mcp add --transport stdio --scope project \
apple-notes \
-- /path/to/Apple-MCPs/AppleNotes-MCP/start.sh
```
</details>
## 启动检查清单
- 启动服务器：`./start.sh`
- 将 `start.sh` 路径添加到您的 MCP 客户端
- 重新连接客户端，以便服务器加载
- 调用健康工具以验证它是否正常工作
- 如果权限失败，请调用权限指南工具
- 修复权限后，请调用重新检查工具（或 `shortcuts_refresh_state` 用于快捷方式）
- 当套件声称具有原生 MCP 支持的某个功能时，请不要将 shell、`curl`、UI 抓取或外部 API 视为通过结果
- 对于地图，通过原生 Apple 地图 MCP 成功需要原生通过
- 对于专注和通知，通过需要真实的 MCP 输出。不要编造活跃的专注状态或通知中心历史记录，而套件实际上并未公开这些信息。
## 协议验证
对于正常的本地代理设置，请使用 `stdio`。Apple-Tools-MCP 还支持 `streamable-http` 用于协议验证和托管客户端。
在 Apple-Tools-MCP 上运行完整的官方活动服务器一致性套件：
```bash
cd /path/to/Apple-MCPs/Apple-Tools-MCP
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./start.sh
```
在另一个 shell 中：
```bash
npx -y @modelcontextprotocol/conformance server \
--url http://127.0.0.1:8765/mcp \
--suite active
```
在所有已发布的服务器上运行轻量级检查：
```bash
cd /path/to/Apple-MCPs
bash scripts/inspector_smoke.sh
```
仓库还包括 [protocol-ci.yml](./.github/workflows/protocol-ci.yml) 中的 GitHub Actions，用于检查这两个检查。
## 健康和恢复工具
| 服务器 | 健康工具 | 权限或恢复工具 |
| --- | --- | --- |
| Apple-Tools-MCP | `apple_health` | `apple_permission_guide`，`apple_recheck_permissions` |
| Apple 邮件 MCP | `mail_health` | `mail_permission_guide`，`mail_recheck_permissions` |
| Apple 日历 | `calendar_health` | `calendar_permission_guide`，`calendar_recheck_permissions` |
| Apple 提醒事项 MCP | `reminders_health` | `reminders_permission_guide`，`reminders_recheck_permissions` |
| Apple 消息 MCP | `messages_health` | `messages_permission_guide`，`messages_recheck_permissions` |
| Apple 联系人 MCP | `contacts_health` | `contacts_permission_guide`，`contacts_recheck_permissions` |
| Apple 笔记 MCP | `notes_health` | `notes_permission_guide`，`notes_recheck_permissions` |
| Apple 快捷方式 MCP | `shortcuts_health` | `shortcuts_permission_guide`，`shortcuts_refresh_state` |
| Apple 文件 MCP | `files_health` | `files_permission_guide` |
| Apple 系统 MCP | `system_health` | `system_permission_guide` |
| Apple 地图 MCP | `maps_health` | `maps_permission_guide` |
## macOS 权限
不同的 Apple 应用程序需要不同的权限：
| 服务器 | macOS 可能要求什么 |
| --- | --- |
| Apple 邮件 | 对邮件的自动化访问 |
| Apple 日历 | 日历访问 |
| Apple 提醒事项 | 提醒事项访问 |
| Apple 消息 | 对消息的自动化访问，以及历史记录的完全磁盘访问 |
| Apple 联系人 | 联系人访问 |
| Apple 笔记 | 对笔记的自动化访问 |
| Apple 快捷方式 | 通常不需要单独的隐私提示 |
| Apple 文件 | 无隐私提示，访问仅限于配置的允许根目录 |
| Apple 系统 | 一些操作可能会触发系统事件、可访问性或自动化提示 |
| Apple 地图 | 无隐私提示，但本地 Swift 助手编译需要 Xcode 命令行工具 |
## 仓库布局
- `Apple-Tools-MCP/`，统一服务器
- `AppleFiles-MCP/`，文件
- `AppleSystem-MCP/`，系统
- `AppleMaps-MCP/`，地图
- `AppleContacts-MCP/`，联系人
- `AppleMail-MCP/`，邮件
- `Apple-Calendar-MCP/`，日历
- `AppleReminders-MCP/`，提醒事项
- `AppleMessages-MCP/`，消息
- `AppleNotes-MCP/`，笔记
- `AppleShortcuts-MCP/`，快捷方式
- `SharedAppleBridge/`，事件图基尔服务器使用的共享原生桥接代码
- `.build/`，本地助手构建输出
## 注意事项
- 此套件适用于 macOS。
- Apple 消息历史记录访问仍然需要完全磁盘访问。
- 统一服务器文件夹为 `Apple-Tools-MCP`。
- 日历服务器文件夹为 `Apple-Calendar-MCP`。
- Apple 文件访问仅限于 `APPLE_FILES_MCP_ALLOWED_ROOTS` 中的根目录。
- Apple 系统写入操作可以通过 `APPLE_SYSTEM_MCP_SAFETY_MODE` 限定范围。
- Apple 地图依赖于本地 Swift 助手和 Xcode 命令行工具，用于搜索和方向。
- Apple-Tools-MCP 可以在 `~/.apple-tools-mcp/preferences.json` 或 `APPLE_AGENT_MCP_STATE_FILE` 中的路径下持久化助手默认值。
- Apple-Tools-MCP 还会在 `~/.apple-tools-mcp/actions.json` 中存储最近的助手操作，用于审核和撤销工作流。
- Apple-Tools-MCP 现在聚合了文件、系统和地图，以及特定于应用程序的 Apple 服务器。
- `APPLE_AGENT_MCP_CONFORMANCE_MODE=1` 仅用于协议验证。它在 Apple-Tools-MCP 上添加了官方 MCP 一致性夹具，并将 HTTP 模式切换为完全流式行为。
- Apple-Tools-MCP 现在包括任务功能性的简报工具、`apple_generate_daily_briefing`、`apple_generate_weekly_briefing` 和 `apple_triage_communications_task`。
- Apple-Tools-MCP 还包括提示回退工具、`apple_list_prompts` 和 `apple_get_prompt`，适用于仅限工具的 MCP 客户端。
- 独立服务器现在公开提示回退工具和显式资源订阅或取消订阅处理程序，以便在更薄的 MCP 客户端中，工作流降级更清洁。
- Apple 邮件现在包括线程助手、`mail_get_thread`、`mail_reply_latest_in_thread` 和 `mail_archive_thread`。
- Apple 联系人现在可以创建、更新和删除带有标记的电话号码和电子邮件地址的联系人。
- 邮件搜索需要查询字符串。使用发件人、主题片段或 `*` 作为通配符。
- 提醒事项 `due_date` 需要时区偏移量，如 `yyyy-MM-ddTHH:mm:ss-HH:00`。
- `service_name` 在 iMessage 发送时应省略。
