苹果日历MCP服务器
 ](https://nodejs.org/) 
注： 此MCP服务器需要带Apple日历的macOS。
一个模型上下文协议（MCP）服务器，为Claude提供对Apple Calendar的完全访问权限，以实现智能调度、日历管理和时间管理协助。
______________________________________________________________________
目录
______________________________________________________________________
我为什么建造这个
Apple的Calendar.app可以查看您的日程安排。添加事件是垃圾。“在工作日历中创建明天下午2点的活动团队会议”——如果不点击6次，就无法完成此操作。Apple的UI中不存在自然语言调度。
我希望我的代理能够像处理其他事情一样处理日程安排：通过工具调用。“下午1点与Sarah共进午餐”→ 日历条目。“明天找空时间开一个1小时的会”→ 时间段建议。“我星期五下午3点有空吗？”→ 是/否，包含冲突细节。
这是一个MCP服务器，因为Claude Code应该能够以编辑代码或运行测试的方式安排事情——作为工具调用，而不是手动GUI交互。
______________________________________________________________________
特性
日历管理
- 列表_日历 -列出所有可用日历
- create_calendar -创建新日历
- delete_calendar -删除日历
- 重命名_日历 -重命名现有日历
活动操作
- create_event -使用自然语言日期解析创建事件
- 支持“明天下午3点”、“下周五”、“2小时后”等。
- list_事件 -列出特定日历中的事件
- list_all_事件 -列出所有日历中的事件
- 搜索事件 -按关键字搜索事件（搜索标题、位置、描述）
- update_事件 -更新事件属性
- 删除事件 -删除事件
- move_event -在日历之间移动事件
智能调度
- find_free_time -查找可用的时间段
- 可选营业时间过滤器（上午9点至下午5点）
- check_冲突 -检查日程安排冲突
- 建议最佳时间 -基于人工智能的时间建议和偏好
模板
- create_template -将事件配置保存为可重用模板
- 使用模板 -从模板创建事件
- list_templates -查看所有已保存的模板
- delete_template -删除模板
分析
- 分析时间表 -了解以下内容：
- 会议密度（每天会议） - 会议总时间 - 每日进度明细
______________________________________________________________________
当前痛点
以下是我正在积极参与的战斗：
- AppleScript是唯一的接口 -Calendar.app没有公共API。一切都会过去的
osascript其易碎、缓慢且没有错误处理。如果Calendar.app处于奇怪的状态（同步、锁定、背景），AppleScript将挂起或返回垃圾。
- 仅限macOS --这本质上锁定了我的Linux桌面。我无法在我的主机上运行这个。它只适用于工作中的MacBook。对于一个应该在任何地方运行的代理生态系统来说，这是一个我还没有解决的限制。
- 权限对话框对用户不利 --“允许终端控制日历？”--macOS只显示一次此对话框，如果用户意外点击“不允许”，服务器将永远无声地失败。重置权限需要深入的“系统首选项”导航。
- 无重复事件 --服务器可以创建一次性事件，但不能创建重复事件（“每周一上午9点”）。AppleScript支持RRULE，但MCP服务器尚未公开它。这是最需要的缺失功能。
- 数据解析边缘案例 —
chrono-node处理95%的自然语言日期，但在模棱两可的情况下失败（周日为“下周”，周六为“本周末”）。我有后备逻辑，但这是启发式的。
- 无同步状态感知 --当您创建事件时，Calendar.app可能正在与iCloud同步。AppleScript返回成功，但事件在30秒内不会出现。服务器无法知道事件是否真的发生了。
______________________________________________________________________
最终目标——走向何方
短期（现在→ 3 月）
- 周期性事件 --通过AppleScript公开RRULE，支持“每周一上午9点”
- 更好的权限处理 --检测权限失败，提供明确的修复说明
- 同步状态轮询 --验证创建后实际出现的事件
中期（3-6个月）
- 跨平台日历 -抽象日历后端，使其通过相同的MCP接口与Google calendar API（Linux）和Apple calendar（macOS）一起工作
- 与代理生态系统集成 --JobHound通过同一日历界面安排面试提醒，Blackreach安排研究截止日期
- 主动调度 --“你明天下午有3个小时的空闲时间——想让我安排深度工作吗？”
长期（6-12个月）
- 通用日历代理 --一个MCP服务器，可与Apple日历、Google日历、Outlook和任何CalDAV服务器通信
- 进度优化 --分析你的模式，建议更好的会议时间，保护Deep Work区块，自动拒绝低优先级冲突
- 与Bifrost集成 --神话研究截止日期、代理任务时间表，所有这些都可以在一个日历视图中看到
______________________________________________________________________
安装
先决条件
- macOS（苹果日历所需）
- Node.js 20+和npm
- 苹果日历应用程序
- Claude 代码命令行工具
设置
- 克隆/安装服务器：
cd ~/mcp-servers/calendar
npm install
npm run build- 授予日历访问权限：
- 系统首选项>安全与隐私>隐私>自动化 - 启用终端（或您的终端应用程序）来控制日历
- 配置克劳德代码：
服务器已在以下位置配置： ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"apple-calendar": {
"command": "node",
"args": [
"/path/to/apple-calendar-mcp/dist/index.js"
]
}
}
}- 重新启动Claude代码：
当Claude Code启动时，服务器将自动启动。
______________________________________________________________________
使用示例
基本日历操作
"List my calendars"
"Create a calendar called Work"
"Rename the Work calendar to Office"
"Delete the Test calendar"创建事件
"Create an event 'Team Meeting' tomorrow at 2pm in the life calendar"
"Schedule 'Dentist Appointment' next Tuesday at 10am with 1 hour duration"
"Add 'Coffee with Sarah' at 3pm today at Starbucks"自然语言数据解析
服务器理解：
- “明天下午3点”
- “下周五”
- “2小时后”
- “1月15日上午10:30”
- “这个周末”
智能调度
"Find free time tomorrow for a 1 hour meeting"
"Check if I'm free Friday at 3pm"
"Suggest the best time for a meeting next week, I prefer mornings"
"Find free time during business hours only"搜索事件
"Search for 'dentist' events this month"
"Find all events with 'meeting' in the title from last week"
"Search for events at 'Starbucks' this year"使用模板
"Create a template called 'standup' with 15 minute duration"
"Schedule a standup meeting from template tomorrow at 9am"
"List all my templates"分析
"Analyze my schedule for this week"
"Show insights for next week"
"How busy am I this month?"______________________________________________________________________
建筑
~/mcp-servers/calendar/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server with all tools
│ ├── applescript/
│ │ ├── bridge.ts # AppleScript execution wrapper
│ │ ├── calendar-ops.ts # Calendar CRUD operations
│ │ └── event-ops.ts # Event CRUD operations
│ ├── utils/
│ │ ├── date-parser.ts # Natural language date parsing (chrono-node)
│ │ └── conflict-detector.ts # Conflict detection & free time finding
│ └── storage/
│ └── database.ts # SQLite for templates & history
├── storage/
│ └── calendar.db # SQLite database (auto-created)
└── dist/ # Compiled JavaScript______________________________________________________________________
技术细节
自然语言处理
- 用途
chrono-node用于解析自然语言日期 - 支持相对日期、绝对日期和常用短语
- 自动处理时区和模糊性
AppleScript集成
- 直接的
osascript需要可靠的日历访问 - AppleScript的正确日期格式
- 字符串转义以防止注入攻击
- 日历API失败的错误处理
数据存储
- 用于模板和历史记录的SQLite数据库
- 默认首选项设置
- 撤消历史记录（最近100次操作）
冲突检测
- 高效的时隙重叠检查
- 利用可配置的时间间隔寻找空闲时间
- 营业时间过滤
- 基于偏好的最佳时间建议
______________________________________________________________________
配置
默认设置（存储在SQLite中）：
default_calendar：“生命”default_event_duration：1小时（3600000毫秒）business_hours_start：9（上午9点）business_hours_end：17（下午5点）
______________________________________________________________________
发展
构建
npm run build开发模式（带自动重新加载）
npm run dev使用MCP检查器进行调试
npx @modelcontextprotocol/inspector npx tsx src/index.ts______________________________________________________________________
故障排除
“不允许日历访问”
解决方案： 在“系统首选项”>“安全与隐私”>“隐私”>自动化中授予自动化权限
服务器未连接
- 检查登录
~/Library/Logs/Claude/ - 验证构建成功：
npm run build - 直接测试：
npx tsx src/index.ts - 确保Calendar.app未处于损坏状态
日期解析失败
- chrono节点处理最常见的格式
- 对于边缘情况，使用明确的格式，如“2024-01-15 10:30am”
- 检查错误消息中的输入格式
事件未出现
- 验证日历名称是否完全匹配（区分大小写）
- 检查Calendar.app是否正在运行
- 刷新Calendar.app视图
______________________________________________________________________
未来的增强功能
v2的潜在功能：
- RRULE支持下的重复事件
- 与会者管理
- 位置自动完成
- 视频会议链路生成
- iCal导入/导出
- 主动进度优化
- 基于机器学习的事件分类
______________________________________________________________________
许可证
麻省理工学院
作者
建造于 空白Phnix