Apple Reminders MCP Server

苹果提醒MCP服务器v0.2.0

macOS上用于Apple提醒的全面模型上下文协议（MCP）服务器，使Claude和Cursor AI等AI助手能够使用自然语言管理提醒。

🎉 v0.2.0的新增功能

• ✅ 完整的CRUD操作 （创建、读取、更新、删除）
• ✅ 定期提醒 （每日、每周、每月、每年模式）
• ✅ 基于位置的提醒 （地理围栏触发到达/离开）
• ✅ 多个警报 每次提醒（绝对和相对）
• ✅ 搜索功能 （标题和注释中的文本搜索）
• ✅ 基于日期的查询 （今天，逾期，已完成）
• ✅ 12个MCP工具 （比v0.1.0中的3有所增加）

特性

✨ 综合集成

• 提醒时的完整CRUD操作（创建、读取、更新、删除、完成）
• 搜索和筛选提醒
• 基于日期的查询（今天、逾期、已完成）
• 约70%的Apple提醒功能覆盖率

🚀 由EventKit+Swift提供技术支持

• 本地EventKit集成，实现最佳性能
• ✅ 定期提醒 （每日、每周、每月、自定义）
• ✅ 基于位置的提醒 （到达/离开触发器）
• ✅ 多个警报 每次提醒
• ✅ 标记变通方法 （编码在注释中）

🔒 隐私第一

• 所有操作都在Mac上本地进行
• 没有云服务或外部API
• 尊重macOS权限系统

先决条件

• macOS 13.0+ （文图拉或更高版本）
• Node.js 18+
• Swift 5.9+ （Xcode命令行工具）

快速开始

1.安装和构建

# Clone or download this repository
cd apple-reminders-mcp-server

# Run setup (installs dependencies and builds everything)
npm run setup

2.请求权限

./swift-cli/.build/release/reminders-cli request-access

在“系统设置”>“隐私和安全”>“提醒”中授予权限。

3.配置您的AI助手

适用于克劳德桌面

编辑 ~/.config/claude/claude_desktop_config.json:

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

适用于Cursor AI

编辑光标MCP设置，以添加具有相同配置的此服务器。

4.重新启动您的AI助手

重新启动Claude Desktop或Cursor以加载MCP服务器。

可用工具（共12个）

提醒管理（6个工具）

1. create_reminder -创建具有全面属性的提醒

- 基本：标题、注释、截止日期、优先级、标签、URL - 高级：重复模式、位置触发、多个警报

1. update_reminder -更新现有提醒
2. delete_reminder -永久删除提醒
3. complete_reminder -将提醒标记为完成
4. uncomplete_reminder -将提醒标记为不完整
5. get_reminders -列出所有提醒（按完成情况筛选）

列表管理（1个工具）

1. get_all_lists -获取所有提醒列表

搜索和查询（5个工具）

1. search_reminders -按标题/注释中的文本搜索
2. get_todays_reminders -收到今天到期的提醒
3. get_overdue_reminders -获取逾期提醒
4. get_completed_reminders -获取已完成的提醒（可选日期范围）

使用示例

基本提醒

"Create a reminder to buy milk"
"Show me all my reminders"
"Mark the milk reminder as complete"
"Delete the milk reminder"

定期提醒

"Create a weekly reminder for team meeting every Monday at 10am"
"Set up a daily reminder to take medication at 8am"
"Create a monthly reminder on the 1st to pay rent"

基于位置的提醒

"Remind me to buy groceries when I arrive at the supermarket"
"Create a reminder to call mom when I leave work"

搜索和筛选

"Search for reminders about meetings"
"Show me today's reminders"
"What reminders are overdue?"
"Show me completed reminders from last week"

高级功能

""Create an URGENT reminder with priority 1 to call the client"
"Create a high-priority reminder with tags #work #urgent""
"Set up a reminder with multiple alarms - 1 day before and 1 hour before"
"Create a reminder that repeats every other week"

建筑

AI Assistant (Claude/Cursor)
    ↓ MCP Protocol (stdio)
TypeScript MCP Server (Node.js)
    ↓ child_process + JSON
Swift CLI Binary (EventKit)
    ↓ EventKit Framework
Apple Reminders.app

为什么选择EventKit+Swift？

该项目使用苹果的 EventKit框架 通过Swift CLI而不是更简单的JXA（JavaScript for Automation）方法。原因如下：

JXA限制 （POC测试和记录）：

• ❌ 不支持 定期提醒 （每日、每周、每月模式）
• ❌ 不支持 基于位置的提醒 （地理围栏）
• ❌ 无法访问 标签 （需要文本变通方法）
• ❌ 不支持 子任务 （未在API中暴露）
• ❌ 多个警报 无法访问
• ❌ JXA基本上被苹果放弃了（自2014年以来没有更新）

EventKit优势:

• ✅ 完全访问 70%以上的提醒功能 通过官方苹果API
• ✅ 本地支持 定期提醒 规则复杂
• ✅ 本地支持 位置触发器 （到达/离开）
• ✅ 本地支持 多个警报 每次提醒
• ✅ 积极维护 由Apple发布新的macOS版本
• ✅ 更好 演出 和 可靠性

权衡：EventKit需要Swift编译，但好处远远超过了最小的额外设置复杂性。Swift CLI在安装过程中只构建一次，可以访问几乎所有公开可用的提醒功能。

功能覆盖率（~70%）

✅ 全力支持

• 核心业务：创建、读取、更新、删除、完成
• 定期提醒：每日、每周、每月、每年都有自定义规则
• 位置提醒：Geofence触发器（到达/离开）
• 多个警报：绝对（特定时间）和相对（到期日前）
• 搜索：标题和注释中的文本搜索
• 日期查询：今天，过期，已完成日期范围
• 列表：获取所有列表，指定提醒列表
• 优先：0=无，1=紧急（！！！），5=中等，9=低
• 标记状态：将提醒标记为重要（旗帜图标）
• 注释和URL：富文本注释、相关URL

⚠️ 权变措施

• 标签：编码为 [#tag] 在笔记字段中（可搜索）
• 子任务：使用结构化笔记或链接提醒

⚠️ API限制（尚未在EventKit中提供）

• 紧急警报 （macOS 26.2+）：新的“紧急”警报功能未在EventKit API中公开

- 解决方法：使用 priority: 1 + flagged: true +定期警报 - 看 URGENT_FEATURE_STATUS.md 详情

• 苹果尚未宣布EventKit何时/是否支持此功能

❌ 不支持（专用Apple API）

• 本地标签功能
• 子任务功能
• 智能列表

发展

项目结构

apple-reminders-mcp-server/
├── swift-cli/              # Swift CLI (EventKit integration)
│   ├── Sources/
│   │   ├── RemindersKit/   # Core library
│   │   │   ├── Models/     # Swift models
│   │   │   └── *.swift     # Managers
│   │   └── reminders-cli/  # CLI executable
│   └── Package.swift
├── src/                    # TypeScript MCP Server
│   ├── index.ts           # MCP server entry
│   ├── executor/          # Swift CLI executor
│   ├── tools/             # 12 MCP tool handlers
│   ├── validation/        # Zod schemas
│   └── types/             # TypeScript types
└── docs/                  # Documentation

开发命令

# Build everything
npm run build          # Build TypeScript
npm run build:swift    # Build Swift CLI

# Development mode
npm run dev            # Watch mode for TypeScript

# Testing
npm test               # Run tests
npm run lint           # Lint code
npm run format         # Format code

# Cleanup
npm run clean          # Remove build artifacts

从源头构建

# Build Swift CLI (release mode)
cd swift-cli
swift build --configuration release

# Build TypeScript
cd ..
npm run build

测试

直接测试Swift CLI

# Create an urgent reminder (priority 1 = shows !!! in Reminders.app)
./swift-cli/.build/release/reminders-cli create-reminder '{"title":"URGENT: Fix bug","priority":1}'

# Create recurring reminder
./swift-cli/.build/release/reminders-cli create-reminder '{
  "title":"Weekly Meeting",
  "dueDate":"2026-01-13T10:00:00Z",
  "recurrence":{"frequency":"weekly","interval":1}
}'

# Search reminders
./swift-cli/.build/release/reminders-cli search-reminders '{"searchText":"meeting"}'

# Get today's reminders
./swift-cli/.build/release/reminders-cli get-todays-reminders

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector node dist/index.js

高级功能

定期提醒

创建按计划重复的提醒：

{
  "title": "Weekly team sync",
  "dueDate": "2026-01-13T10:00:00Z",
  "recurrence": {
    "frequency": "weekly",    // daily, weekly, monthly, yearly
    "interval": 1,            // every N weeks
    "daysOfWeek": [2],        // Monday (1=Sunday, 7=Saturday)
    "endDate": "2026-12-31T00:00:00Z"  // optional
  }
}

基于位置的提醒

根据位置触发提醒：

{
  "title": "Buy groceries",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 100,           // meters
    "proximity": "enter",    // or "leave"
    "title": "Whole Foods"
  }
}

多个警报

在提醒中添加多个通知：

{
  "title": "Important meeting",
  "dueDate": "2026-01-15T14:00:00Z",
  "alarms": [
    {
      "type": "relative",
      "relativeOffset": -86400  // 1 day before (in seconds)
    },
    {
      "type": "absolute",
      "absoluteDate": "2026-01-15T13:00:00Z"  // 1 hour before
    }
  ]
}

故障排除

权限不足

1. 跑 ./swift-cli/.build/release/reminders-cli request-access
2. 在“系统设置”>“隐私和安全”>“提醒”中授予权限
3. 重启你的AI助手

未找到Swift CLI

1. 构建Swift命令行界面： npm run build:swift
2. 验证： ls swift-cli/.build/release/reminders-cli

工具不工作

1. 直接用JSON测试Swift CLI
2. 在AI助手中检查MCP服务器日志
3. 使用MCP检查器进行隔离调试

路线图

✅ 完成

• \[x\] 完整的CRUD操作
• \[x\] 搜索和筛选
• \[x\] 基于日期的查询
• \[x\] 定期提醒
• \[x\] 基于位置的提醒
• \[x\] 多个警报

🔄 未来的增强功能

• \[\]列表管理（创建、更新、删除列表）
• \[\]批量操作
• \[\]包含建议的丰富错误消息
• \[\]性能优化
• \[\]用于分发的预编译二进制文件
• \[\]npm包发布

贡献

这是一个学习项目。欢迎投稿、问题和功能请求！

许可证

麻省理工学院

参考文献

• MCP文件
• EventKit文档
• FradSer的mcp服务器苹果事件

______________________________________________________________________

内置于❤️ 对于MCP生态系统

版本0.2.0 |更新于2026年1月