MCP server that provides native integration with Apple Reminders and Calendar on macOS.
npm install mcp-server-apple-events
English | 简体中文
一个为 macOS 提供原生 Apple Reminders 和 Calendar 集成的 Model Context Protocol (MCP) 服务器。该服务器允许你通过标准化接口与 Apple Reminders 和 Calendar Events 进行交互,具有全面的管理功能。

- Node.js 18 或更高版本
- macOS(Apple Reminders 集成所需)
- Xcode Command Line Tools(编译 Swift 代码所需)
- pnpm(推荐用于包管理)
Apple 已将提醒事项和日历权限拆分为「仅写入」与「完全访问」范围。Swift 桥接层声明了以下隐私键,确保在你授权后 Claude 可以安全读取并写入所选数据:
- NSRemindersUsageDescription
- NSRemindersFullAccessUsageDescription
- NSRemindersWriteOnlyAccessUsageDescription
- NSCalendarsUsageDescription
- NSCalendarsFullAccessUsageDescription
- NSCalendarsWriteOnlyAccessUsageDescription
当授权状态为 notDetermined 时,CLI 会调用 requestFullAccessToReminders / requestFullAccessToEvents,macOS 会弹出对应的授权对话框。如果系统遗失权限记录,可运行 ./check-permissions.sh 重新触发请求。
若 Claude 的工具调用依旧遇到权限错误,Node.js 层会自动运行一段最小化的 AppleScript(osascript -e 'tell application "Reminders" …')来唤起系统弹窗,然后再次重试 Swift CLI。
验证命令
``bash`
pnpm test -- src/swift/Info.plist.test.ts
测试会确保所有必须的 usage-description 字段在发布前均已就绪。
通过 npm 全局安装:
`bash`
npm install -g mcp-server-apple-events
1. 打开 Cursor
2. 打开 Cursor 设置
3. 点击侧边栏中的 "MCP"
4. 点击 "Add new global MCP server"
5. 使用以下设置配置服务器:
`json`
{
"mcpServers": {
"apple-reminders": {
"command": "mcp-server-apple-events",
"args": []
}
}
}
1. 打开 ChatWise
2. 进入设置
3. 导航至工具部分
4. 点击 "+" 按钮
5. 使用以下设置配置工具:
- 类型:stdioapple-reminders
- ID:mcp-server-apple-events
- 命令:
- 参数:(留空)
你需要配置 Claude Desktop 以识别 Apple Events MCP 服务器。有两种方式可以访问配置:
#### 方式 1:通过 Claude Desktop 界面
1. 打开 Claude Desktop 应用
2. 从左上角菜单栏启用开发者模式
3. 打开设置并导航至开发者选项
4. 点击编辑配置按钮打开 claude_desktop_config.json
#### 方式 2:直接访问文件
macOS:
`bash`
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows:
`bash`
code %APPDATA%\Claude\claude_desktop_config.json
将以下配置添加到你的 claude_desktop_config.json:
`json`
{
"mcpServers": {
"apple-reminders": {
"command": "mcp-server-apple-events",
"args": []
}
}
}
要使更改生效:
1. 完全退出 Claude Desktop(不仅仅是关闭窗口)
2. 重新启动 Claude Desktop
3. 查看工具图标以验证 Apple Events 服务器是否已连接
配置完成后,你可以让 Claude 与你的 Apple Reminders 进行交互。以下是一些示例提示:
创建一个明天下午 5 点的"买杂货"提醒。
添加一个"打电话给妈妈"的提醒,备注"询问周末计划"。
在"工作"列表中创建一个下周五到期的"提交报告"提醒。
创建一个带URL的提醒"查看这个网站:https://google.com"。
`
$3
`
将"买杂货"提醒的标题更新为"买有机杂货"。
将"打电话给妈妈"提醒更新为今天下午 6 点到期。
更新"提交报告"提醒并将其标记为已完成。
将"买杂货"的备注更改为"别忘了牛奶和鸡蛋"。
`$3
`
显示我的所有提醒事项。
列出"购物"列表中的所有提醒事项。
显示我已完成的提醒事项。
`$3
`
显示所有提醒事项列表。
显示"工作"列表中的提醒事项。
`服务器将:
- 处理你的自然语言请求
- 与 Apple 原生提醒事项应用交互
- 向 Claude 返回格式化结果
- 维护与 macOS 的原生集成
结构化提示库
该服务器提供统一的提示注册表,可通过 MCP 的
ListPrompts 和 GetPrompt 端点访问。每个模板都共享使命、上下文输入、编号流程、约束、输出格式和质量标准,让下游助手获得可预测的框架,而无需解析松散的自由格式示例。- daily-task-organizer —— 可选
today_focus(你今天最想完成的重点)生成当日执行蓝图,在优先级工作与恢复时间之间保持平衡。支持智能任务聚类、专注时间段安排、自动提醒列表组织,并会在大量今日到期的提醒需要固定时段时,按照到期时间自动创建日历时间块。快速完成类任务簇会转换为以提醒到期时间结束的 15 分钟「Focus Sprint — [Outcome]」日历占位,而标准任务则对应 30、45 或 60 分钟的事件,并以同一到期时间窗口为锚点。
- smart-reminder-creator —— 可选 task_idea(你想做的一句话描述),生成优化调度的提醒结构。
- reminder-review-assistant —— 可选 review_focus(如“逾期”或某个清单名)用于审计与优化现有提醒。
- weekly-planning-workflow —— 可选 user_ideas(您本周想要完成的想法和目标)指导周一至周日的重置,时间区块与现有列表相关联。$3
- 提示严格限制在 Apple Reminders 原生能力范围内(无第三方自动化),并在提交不可逆操作前询问缺失上下文。
- 共享格式使输出可渲染为 Markdown 部分或表格,无需客户端应用程序的额外解析胶水。
- 每次修改提示文案后运行
pnpm test -- src/server/prompts.test.ts 以断言元数据、模式兼容性和叙述组装。可用的 MCP 工具
服务器现在按照服务域暴露 MCP 工具,对应提醒事项与日历的不同资源:
$3
工具名称:
reminders_tasks用于管理单个提醒事项任务,支持完整的 CRUD 操作。
操作:
read、create、update、delete主要处理函数:
-
handleReadReminders() - 带筛选选项读取提醒事项
- handleCreateReminder() - 创建新的提醒事项
- handleUpdateReminder() - 更新现有提醒事项
- handleDeleteReminder() - 删除提醒事项#### 按操作的参数
读取操作(
action: "read"):
- id (可选):要读取的特定提醒事项的唯一标识符
- filterList (可选):要展示的提醒事项列表名称
- showCompleted (可选):是否包含已完成的提醒事项(默认:false)
- search (可选):根据标题或内容筛选提醒事项的搜索词
- dueWithin (可选):按到期范围筛选("today"、"tomorrow"、"this-week"、"overdue"、"no-date")创建操作(
action: "create"):
- title (必填):提醒事项标题
- dueDate (可选):到期时间,格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
- targetList (可选):要添加到的提醒事项列表名称
- note (可选):提醒事项备注内容
- url (可选):与提醒事项关联的 URL更新操作(
action: "update"):
- id (必填):要更新的提醒事项唯一标识符
- title (可选):提醒事项新标题
- dueDate (可选):新的到期时间,格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
- note (可选):新的备注内容
- url (可选):新的 URL
- completed (可选):设置提醒事项完成状态
- targetList (可选):提醒事项所在列表删除操作(
action: "delete"):
- id (必填):要删除的提醒事项唯一标识符#### 使用示例
`json
{
"action": "create",
"title": "购买食材",
"dueDate": "2024-03-25 18:00:00",
"targetList": "购物",
"note": "别忘了牛奶和鸡蛋",
"url": "https://example.com/shopping-list"
}
``json
{
"action": "read",
"filterList": "工作",
"showCompleted": false,
"dueWithin": "today"
}
``json
{
"action": "delete",
"id": "reminder-123"
}
`$3
工具名称:
reminders_lists用于管理提醒事项列表 —— 查看现有列表或创建新的列表来组织提醒事项。
操作:
read、create、update、delete主要处理函数:
-
handleReadReminderLists() - 读取所有提醒事项列表
- handleCreateReminderList() - 创建新的提醒事项列表
- handleUpdateReminderList() - 更新现有提醒事项列表
- handleDeleteReminderList() - 删除提醒事项列表#### 按操作的参数
读取操作(
action: "read"):
- 无需额外参数创建操作(
action: "create"):
- name (必填):新列表的名称更新操作(
action: "update"):
- name (必填):要更新的列表当前名称
- newName (必填):列表的新名称删除操作(
action: "delete"):
- name (必填):要删除的列表名称#### 使用示例
`json
{
"action": "create",
"name": "项目 Alpha"
}
`$3
工具名称:
calendar_events用于处理 EventKit 日历事件(时间块),提供 CRUD 能力。
操作:
read、create、update、delete主要处理函数:
-
handleReadCalendarEvents() - 带可选筛选读取事件
- handleCreateCalendarEvent() - 创建日历事件
- handleUpdateCalendarEvent() - 更新现有事件
- handleDeleteCalendarEvent() - 删除日历事件#### 按操作的参数
读取操作(
action: "read"):
- id (可选):要读取的事件唯一标识符
- filterCalendar (可选):按日历名称筛选
- search (可选):在标题、备注或地点中搜索关键字
- startDate (可选):筛选在此日期之后开始的事件
- endDate (可选):筛选在此日期之前结束的事件创建操作(
action: "create"):
- title (必填):事件标题
- startDate (必填):开始时间
- endDate (必填):结束时间
- targetCalendar (可选):要创建到的日历名称
- note、location、url、isAllDay (可选):附加元数据更新操作(
action: "update"):
- id (必填):事件标识符
- 其余字段与创建参数一致,用于选择性更新删除操作(
action: "delete"):
- id (必填):要删除的事件标识符$3
工具名称:
calendar_calendars用于返回 EventKit 中可用的日历集合。在创建或更新事件前可先确认日历标识。
操作:
read主要处理函数:
-
handleReadCalendars() - 列出所有日历的 ID 与名称使用示例
`json
{
"action": "read"
}
`示例响应
`json
{
"content": [
{
"type": "text",
"text": "### Calendars (Total: 3)\n- Work (ID: cal-1)\n- Personal (ID: cal-2)\n- Shared (ID: cal-3)"
}
],
"isError": false
}
`#### 返回格式
成功响应:
`json
{
"content": [
{
"type": "text",
"text": "Successfully created reminder: 购买食材"
}
],
"isError": false
}
`组织策略
服务器通过四个内置策略提供智能提醒事项组织功能:
$3
基于优先级关键词自动分类提醒事项:
- 高优先级:包含"紧急"、"重要"、"关键"、"紧急"等词
- 中优先级:标准提醒事项的默认类别
- 低优先级:包含"稍后"、"某天"、"最终"、"也许"等词$3
基于提醒事项的截止日期进行组织:
- 已过期:过去的截止日期
- 今天:今天到期的提醒事项
- 明天:明天到期的提醒事项
- 本周:本周内到期的提醒事项
- 下周:下周到期的提醒事项
- 未来:下周之后到期的提醒事项
- 无日期:没有截止日期的提醒事项$3
通过内容分析智能分类提醒事项:
- 工作:商务、会议、项目、办公室、客户相关
- 个人:家庭、朋友、自我护理相关
- 购物:购买、商店、采购、杂货相关
- 健康:医生、运动、医疗、健身、锻炼相关
- 财务:账单、付款、金融、银行、预算相关
- 旅行:旅行、假期、航班、酒店相关
- 教育:学习、课程、学校、书籍、研究相关
- 未分类:不匹配任何特定类别的提醒事项$3
简单的二元组织:
- 活跃:未完成的提醒事项
- 已完成:已完成的提醒事项$3
按优先级组织所有提醒事项:
`
按优先级组织我的提醒事项
`对工作相关的提醒事项进行分类:
`
从工作列表按类别组织提醒事项
`对过期项目进行排序:
`
按截止日期组织过期提醒事项
`开发
1. 使用 pnpm 安装依赖(保持 Swift 桥接与 TypeScript 版本一致):
`bash
pnpm install
`2. 在启动前构建 Swift 二进制(TypeScript 使用运行时执行):
`bash
pnpm build
`3. 运行全量测试,验证 TypeScript、Swift 桥接和提示模板:
`bash
pnpm test
`4. 在提交前执行 Biome 检查:
`bash
pnpm exec biome check
`$3
CLI 入口内建项目根目录回退逻辑。即使从
dist/ 等子目录或编辑器任务运行器启动,服务器也能在向上最多十层目录内定位 package.json 并加载随附的 Swift 二进制。若你自定义目录结构,请确保清单文件仍在该查找深度之内,以维持这一保证。$3
-
pnpm build - 构建 Swift 二进制文件(启动服务器前必需)
- pnpm build:swift - 仅构建 Swift 二进制文件
- pnpm dev - 通过 tsx 以文件监视模式运行 TypeScript 开发服务器(运行时 TS 执行)
- pnpm start - 通过 stdio 启动 MCP 服务器(如果没有构建则自动回退到运行时 TS)
- pnpm test - 运行完整的 Jest 测试套件
- pnpm check - 运行 Biome 格式化和 TypeScript 类型检查$3
运行时依赖:
-
@modelcontextprotocol/sdk ^1.20.2 - MCP 协议实现
- moment ^2.30.1 - 日期/时间处理实用工具
- exit-on-epipe ^1.0.1 - 优雅的进程终止处理
- tsx ^4.20.6 - TypeScript 执行和 REPL
- zod ^4.1.12 - 运行时类型验证开发依赖:
-
typescript ^5.9.3 - TypeScript 编译器
- @types/node ^24.9.2 - Node.js 类型定义
- @types/jest ^30.0.0 - Jest 类型定义
- jest ^30.2.0 - 测试框架
- babel-jest ^30.2.0 - Babel Jest 转换器
- babel-plugin-transform-import-meta ^2.3.3 - Babel 导入元转换
- ts-jest ^29.4.5 - Jest TypeScript 支持
- @biomejs/biome ^2.3.2` - 代码格式化和静态检查构建工具:
- Swift 二进制文件用于原生 macOS 集成
- TypeScript 编译用于跨平台兼容性
MIT
Contributions welcome! Please read the contributing guidelines first.