Apple Calendar MCP

🚀 apple-calendar-mcp

这是一个通过原生 EventKit API 实现的苹果日历 MCP 服务器，能很好地支持循环事件。

🚀 快速开始

此项目借助苹果原生的 EventKit 框架，利用 predicateForEvents 方法，将循环事件正确展开为指定日期范围内的单个事件，解决了基于 AppleScript 的日历集成无法正确展开循环事件的问题。

✨ 主要特性

• 基于原生 EventKit API，能正确展开循环事件。
• 提供多种 MCP 工具，方便对日历进行操作。

📦 安装指南

选项 1：使用 npm（推荐）

claude mcp add --scope user apple-calendar -- npx apple-calendar-mcp

此命令会自动下载软件包、编译 Swift 桥接程序并注册 MCP 服务器。需要在安装了 Xcode 或 Swift 工具链的 macOS 系统上运行。

安装完成后，授予日历访问权限：

npx apple-calendar-mcp doctor

提示时授予完全访问权限。如果之前拒绝过访问：

tccutil reset Calendar
npx apple-calendar-mcp doctor

选项 2：从源代码安装

git clone https://github.com/EgorKurito/apple-calendar-mcp.git
cd apple-calendar-mcp
./scripts/build.sh

授予日历访问权限：

swift/.build/release/apple-bridge doctor

通过以下方法连接到 Claude Code：

项目级 .mcp.json 将 .mcp.json.example 复制到项目中的 .mcp.json 并更新路径：

{
  "mcpServers": {
    "apple-calendar": {
      "command": "node",
      "args": ["/path/to/apple-calendar-mcp/build/index.js"],
      "env": {
        "APPLE_BRIDGE_BIN": "/path/to/apple-calendar-mcp/swift/.build/release/apple-bridge"
      }
    }
  }
}

用户级 CLI 注册

claude mcp add --scope user apple-calendar \
  node /path/to/apple-calendar-mcp/build/index.js \
  -e APPLE_BRIDGE_BIN=/path/to/apple-calendar-mcp/swift/.build/release/apple-bridge

💻 使用示例

基础用法

检查系统诊断信息

swift/.build/release/apple-bridge doctor

列出日历

swift/.build/release/apple-bridge calendars

获取今天的事件

swift/.build/release/apple-bridge today

获取指定日期范围内的事件（循环事件已展开）

swift/.build/release/apple-bridge events --start "2026-02-01T00:00:00Z" --end "2026-02-28T23:59:59Z"

📚 详细文档

MCP 工具

🔧 技术细节

Claude Code ──stdio JSON-RPC──▶ TypeScript MCP Server ──execa──▶ Swift CLI (apple-bridge) ──EventKit──▶ macOS Calendar

• TypeScript 层：包含 6 个工具的 MCP 服务器，使用 Zod 进行验证，通过 stdio 进行 JSON-RPC 通信。
• Swift 层：使用 EventKit 的 CLI 二进制文件，返回 JSON 封装 {status, data, error}。

📄 许可证

本项目采用 MIT 许可证。

🔧 故障排除

日历访问被拒绝

重置 TCC 权限并重新运行：

tccutil reset Calendar
swift/.build/release/apple-bridge doctor

循环事件未展开

这正是本项目要解决的问题。确保使用 MCP 工具（使用 predicateForEvents），而不是基于 AppleScript 的替代方案。

ISO 8601 解析错误

Swift 二进制文件期望日期格式为 2026-02-07T10:00:00Z 或 2026-02-07T10:00:00.000Z。

🤝 贡献指南

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 运行 ./scripts/build.sh 验证构建。
5. 提交拉取请求。