Apple Events MCP Server

English | 简体中文

一个为 macOS 提供原生 Apple Reminders 与 Calendar 集成的 Model Context Protocol (MCP) 服务器，基于 EventKit 框架。通过标准化接口暴露提醒事项、列表、子任务与日历事件，支持完整 CRUD 操作。

EventKit 后端为独立的 event Swift CLI，以 git submodule 形式 vendor，在 pnpm install 时构建为 bin/event，无需另行 brew install。v1.5.0 后端切换及 event 尚未暴露的写入字段列表见 docs/migration-to-event-cli.md。

目录

• 功能特性
• 系统要求
• 快速开始
• 配置说明
• macOS 权限
• 使用示例
• 可用的 MCP 工具
• 结构化提示库
• 开发
• License
• Contributing

功能特性

• 提醒事项、子任务、提醒列表与日历事件的完整 CRUD
• 优先级（高/中/低/无）、标签与带进度跟踪的清单子任务
• 多条件过滤：完成状态、到期范围、优先级、标签、全文搜索、重复、基于位置
• 灵活日期格式（YYYY-MM-DD、YYYY-MM-DD HH:mm:ss、ISO 8601），具备时区感知
• 基于 EventKit 的原生 macOS 集成——在 Reminders.app / Calendar.app 中配置的值会原样往返于读取响应
• 自动 macOS 权限发现与请求
• 完整 Unicode 支持与全面的输入校验

系统要求

• Node.js 20 或更高版本
• macOS（EventKit 所需）
• Xcode Command Line Tools（仅从源码构建时需要）
• pnpm（推荐）

npm 发布包自带预构建的通用签名 bin/event 二进制，使用 npx 的用户无需安装 Xcode 或 Swift 工具链。从 git 克隆构建时则需要上述依赖。

快速开始

npx mcp-server-apple-events

配置说明

将服务器添加到你的 MCP 客户端。下面的 npx 形式适用于所有客户端；本地构建时，将 command/args 改为指向 dist/index.js 的 node。

Cursor

Settings → MCP → Add new global MCP server：

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

ChatWise

Settings → Tools → "+"，然后：

• 类型：stdio
• ID：apple-reminders
• 命令：mcp-server-apple-events
• 参数：（留空）

Claude Desktop

编辑 claude_desktop_config.json（通过 Settings → Developer Option → Edit Config 打开，或直接编辑 macOS 下的 ~/Library/Application Support/Claude/claude_desktop_config.json / Windows 下的 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

本地构建：

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-apple-events/dist/index.js"]
    }
  }
}

连接本地 MCP 服务器的更多信息见官方 MCP 文档。完全退出 Claude Desktop（不仅是关闭窗口）后重启以使更改生效。

macOS 权限

vendored 的 event CLI 内嵌自己的 Info.plist（bundle id me.frad.event），声明了全部 Reminders 与 Calendar 隐私键，并通过随附的 bin/event-disclaim shim 启动，在 spawn 时主动放弃（disclaim）TCC 责任归属。macOS 因此把权限请求归到 event 自己，而不是启动 MCP 服务的宿主应用——首次调用 EventKit 时弹出的对话框显示的是 "event"，授权记录以 event 的名义出现在 系统设置 > 隐私与安全性 > 提醒事项 / 日历 中，授权一次即覆盖本机所有 MCP 客户端（Claude Desktop、Codex Desktop、Cursor、终端客户端等）。背景见 issue #93。

当 event 检测到 notDetermined 状态时，会调用 requestFullAccessToReminders / requestFullAccessToEvents 触发系统对话框。如果系统遗失权限记录，运行 ./check-permissions.sh 重新触发请求。

日历读取报错

如果看到 Failed to read calendar events，在 系统设置 > 隐私与安全性 > 日历 中将权限切换为 Full Calendar Access，或重新运行 ./check-permissions.sh（脚本同时检查 Reminders 与 Calendars 权限）。

恢复卡死的 TCC 状态（权限弹窗始终不出现）

如果权限对话框始终不弹出，且 系统设置 → 隐私与安全性 → 提醒事项 / 日历 里找不到 event，说明你的机器已处于 stale/misattributed 的 TCC 状态。服务端 disclaim 修复只能防止干净机器进入此状态，无法清除已损坏的条目。恢复方法：

1. 全局重置 Calendar 与 Reminders 的 TCC 条目（按 app 重置常常无效——裸用形式会清除所有条目，才能真正清掉坏状态）：

   tccutil reset Calendar
   tccutil reset Reminders

   这会清除所有应用的 Calendar/Reminders 权限；其他应用下次需要访问时会重新弹窗。

2. 在 Claude 对话中（Claude Desktop 或 Claude Code）重新触发权限，例如输入「使用 AppleScript 查看我的 Calendar 和 Reminders」。授权后服务即可正常使用。见 issue #83。

macOS 26 (Tahoe) 上 could not build module 'Foundation'

如果 pnpm build 失败并提示 could not build module 'Foundation'（或 SDK is not supported by the compiler），说明你的 Swift 工具链版本低于 macOS 26 SDK 的要求——需要 Swift 6.3 或更高，而 macOS 26 早期版本附带的 Command Line Tools 包含的是 Swift 6.2.x。pnpm build:event 会检测此不匹配并打印相同解决方案，详见 issue #85。修复方式：从 App Store 安装 Xcode 26.x，或将 Command Line Tools 更新到附带 Swift 6.3+ 的版本：

softwareupdate --list
sudo softwareupdate -i "Command Line Tools for Xcode-<latest>"
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer   # 若已安装完整版 Xcode
xcrun swiftc --version    # 应显示 Apple Swift version 6.3 或更高

使用示例

配置完成后，让 Claude 与你的 Apple Reminders 和 Calendar 交互。示例提示：

创建一个明天下午 5 点的"买杂货"提醒，带标签 shopping 和 errands。
在"工作"列表中创建一个周五到期的高优先级"完成季度报告"提醒。
创建"Grocery shopping"，包含子任务：milk, eggs, bread, butter。
显示今天到期、带 "urgent" 标签的所有高优先级提醒。
显示我的 "Grocery shopping" 提醒的子任务，并将 "milk" 标记为已完成。
更新"买杂货"——把标题改为"买有机杂货"，优先级设为高。
显示"工作"列表中的提醒，并列出我所有的提醒列表。
在"工作"日历创建明天 9:00–9:30 的 "Team standup" 事件。
显示我下周的日历事件。

服务器处理自然语言请求，与 Apple 原生提醒事项和日历应用交互，并返回格式化结果。

alarms、重复规则与位置触发器在本服务器中是只读的——请在 Reminders.app / Calendar.app 中配置。它们仍会出现在读取结果中并带有视觉指示器。

可用的 MCP 工具

按服务域暴露的工具对应 Apple Reminders 与 Calendar 的不同资源。所有工具都接受一个 action 字段以及按操作区分的参数（MCP 客户端会自动内省完整 Zod schema，此处仅列出操作）。日期字段接受 YYYY-MM-DD、YYYY-MM-DD HH:mm:ss（本地时间）或带时区的 ISO 8601。

| 工具 | 操作 | 说明 | | --- | --- | --- | | reminders_tasks | read、create、update、delete | 优先级、标签、子任务。startDate 通过 update 设置，create 不可用。不支持跨列表搬移。 | | reminders_subtasks | read、create、update、delete、toggle、reorder | 存储在备注字段中（Reminders.app 中人类可读）。 | | reminders_lists | read、create、update、delete | 通过 name → newName 重命名。 | | calendar_events | read、create、update、delete | All-day 由日期格式推断。不支持跨日历搬移。span 限定循环事件删除范围。 | | calendar_calendars | read | 在（可选）startDate/endDate 窗口内至少包含一个事件的日历。 |

调用示例：

{
  "action": "create",
  "title": "买杂货",
  "dueDate": "2024-03-25 18:00:00",
  "targetList": "购物",
  "note": "别忘了牛奶和鸡蛋",
  "priority": 1,
  "tags": ["shopping", "errands"],
  "subtasks": ["牛奶", "鸡蛋", "面包"]
}

{ "action": "read", "filterList": "工作", "dueWithin": "today", "filterPriority": "high", "filterTags": ["urgent"] }

{ "action": "update", "id": "reminder-123", "completed": false, "addTags": ["followup"] }

{ "action": "toggle", "reminderId": "reminder-123", "subtaskId": "a1b2c3d4" }

{ "action": "create", "name": "项目 Alpha" }

{ "action": "create", "title": "Team standup", "startDate": "2026-05-04 09:00:00", "endDate": "2026-05-04 09:30:00", "targetCalendar": "工作" }

读取响应结构

读取响应带有视觉指示器：🔄 重复、📍 基于位置、🏷️ 有标签、📋 有子任务。示例：

- [ ] 买杂货 🏷️📋
  - 列表: 购物
  - ID: reminder-123
  - 优先级: 高
  - 标签: #shopping #errands
  - 子任务 (1/3):
    - [x] 牛奶
    - [ ] 鸡蛋
    - [ ] 面包
  - 到期: 2024-03-25 18:00:00

url 字段存储在原生 url 属性中（可通过 Reminders.app 详情视图的 "i" 图标查看），同时以结构化 URLs: 块追加到备注中，便于解析与多 URL 支持。URL 接受任意合法 URI scheme（http、https、mailto、tel、obsidian、shortcuts 等）；file、javascript、data 等危险 scheme 会被拒绝，http(s) 主机名会经过 SSRF 黑名单校验。

只读字段：alarms、重复规则、位置触发器、structured location、calendar 的 url/availability/isAllDay 以及跨日历搬移无法通过本服务器写入——它们原样来自 Reminders.app / Calendar.app 中配置的值。完整移除字段表与替代方案见 docs/migration-to-event-cli.md。

结构化提示库

服务器提供提示注册表，可通过 MCP 的 ListPrompts / GetPrompt 端点访问。每个模板都共享使命、上下文输入、编号流程、约束、输出格式和质量标准，让下游助手获得可预测的框架。

• daily-task-organizer —— 可选 today_focus；生成当日执行蓝图，在优先级工作与恢复时间之间保持平衡，并为今日到期的提醒自动创建日历时间块。
• smart-reminder-creator —— 可选 task_idea；生成优化调度的提醒结构。
• reminder-review-assistant —— 可选 review_focus（如 overdue 或某个清单名）；审计与优化现有提醒。
• weekly-planning-workflow —— 可选 user_ideas；指导周一至周日的重置，时间区块与现有列表关联。

提示严格限制在 Apple Reminders 原生能力范围内，并在不可逆操作前询问缺失上下文。修改提示文案后运行 pnpm test -- src/server/prompts.test.ts。

开发

pnpm install        # 在 macOS 上 postinstall 会从 vendor/event 构建 bin/event
pnpm build          # TypeScript + vendored event CLI
pnpm test           # Jest 套件：仓库层、Zod 校验、构建脚本、提示模板
pnpm exec biome check   # lint + 格式化

CLI 入口会向上最多十层目录查找 package.json，因此可从嵌套路径（如 dist/ 或编辑器任务运行器）启动而不丢失 bin/event。若自定义目录结构，请确保清单文件仍在该查找深度之内。

脚本

• pnpm build —— TypeScript + vendored event CLI（从源码启动前必需）
• pnpm build:ts —— 仅 TypeScript
• pnpm build:event —— 仅 vendored event CLI（swift build -c release → bin/event）
• pnpm build:release —— 构建并 notarize（发布打包）
• pnpm test / pnpm test:ci —— Jest 套件 / 带覆盖率
• pnpm lint —— Biome 格式化/修复 + TypeScript 类型检查
• pnpm check —— lint + 带覆盖率的测试

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines first.