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. 提交拉取請求。