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. 使用以下设置配置工具：
- 类型：stdio
- ID：
- 命令：
- 参数：（留空）
你需要配置 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 的
和 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 操作。
操作：
、create、update、delete主要处理函数：
-
- 带筛选选项读取提醒事项
- 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
- (可选)：要添加到的提醒事项列表名称
- note (可选)：提醒事项备注内容
- url (可选)：与提醒事项关联的 URL更新操作（
action: "update"）：
- id (必填)：要更新的提醒事项唯一标识符
- title (可选)：提醒事项新标题
- dueDate (可选)：新的到期时间，格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss
- (可选)：新的备注内容
- 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
工具名称：
用于管理提醒事项列表 —— 查看现有列表或创建新的列表来组织提醒事项。
操作：
、create、update、delete主要处理函数：
-
- 读取所有提醒事项列表
- handleCreateReminderList() - 创建新的提醒事项列表
- handleUpdateReminderList() - 更新现有提醒事项列表
- handleDeleteReminderList() - 删除提醒事项列表#### 按操作的参数
读取操作（
action: "read"）：
- 无需额外参数创建操作（
action: "create"）：
- name (必填)：新列表的名称更新操作（
action: "update"）：
- name (必填)：要更新的列表当前名称
- newName (必填)：列表的新名称删除操作（
action: "delete"）：
- name (必填)：要删除的列表名称#### 使用示例
`json
{
"action": "create",
"name": "项目 Alpha"
}
`$3
工具名称：
用于处理 EventKit 日历事件（时间块），提供 CRUD 能力。
操作：
、create、update、delete主要处理函数：
-
- 带可选筛选读取事件
- 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 中可用的日历集合。在创建或更新事件前可先确认日历标识。
操作：
主要处理函数：
-
- 列出所有日历的 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 入口内建项目根目录回退逻辑。即使从
等子目录或编辑器任务运行器启动，服务器也能在向上最多十层目录内定位 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.