JinDaGe - apple-calendar-mcp MCP Details

article

README

🚀 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 工具

| 工具 | 描述 | |------|-------------| | get_calendars | 列出所有日历及其 ID 和颜色 | | get_events | 获取指定日期范围内的事件（正确展开循环事件） | | get_today_events | 获取今天的所有事件 | | search_events | 按标题、地点或备注搜索事件 | | create_event | 创建新的日历事件 | | delete_event | 删除事件（单个事件或所有未来事件） |

🔧 技术细节

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。

🤝 贡献指南

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

apple-calendar-mcp