mcp-ical-swift

一个用于 Apple Calendar 的本地 MCP 服务器，它使用编译后的 Swift 二进制文件来绕过 macOS Sequoia 的 TCC 限制。

为什么存在这个项目

在 macOS Sequoia (26.x) 上，无头进程无法通过标准的 TCC（透明度、同意和控制）机制获取日历访问权限：

• 来自 Python 的 EventKit (例如 PyObjC) 需要 kTCCServiceCalendar，这只能通过系统对话框授予，而无头进程无法触发该对话框。在 Sequoia 的“系统设置” > “隐私与安全性” > “日历”中没有 + 按钮。

• 通过 osascript 的 AppleScript 需要 kTCCServiceAppleEvents（自动化权限），该权限归属于调用二进制文件（通常是 node 或 bun）。直接编辑 TCC 数据库会被 TCC 守护进程的完整性检查静默忽略。

• icalBuddy 和其他 Homebrew 工具在内部使用 EventKit，也会遇到同样的障碍。

编译后的 Swift 二进制文件 (swiftc) 之所以有效，是因为它生成了一个经过 Apple 签名的 Mach-O 可执行文件，该文件从系统 Swift 工具链继承了日历 TCC 权限。当 Node/Bun 通过 execFileSync 生成此二进制文件时，EventKit 会报告 authorizationStatus = .fullAccess 并返回日历数据。

功能

• 列出所有日历

• 列出指定日期范围内的事件

• 按关键字搜索事件

• 创建新事件（支持日历、地点、备注、全天事件）

• 更新现有事件

• 通过 UID 获取完整的事件详情

• 删除事件

• 完全通过 stdio 在本地运行 —— 无网络、无 API 密钥、无云端依赖

先决条件

• macOS Sequoia (26.x) 或更高版本

• Bun 1.1+

• 用于 swiftc 的 Xcode 命令行工具 (xcode-select --install)

• Apple 日历中的日历数据（iCloud、Exchange 或本地日历）

安装

git clone https://github.com/Sealjay/mcp-ical-swift.git
cd mcp-ical-swift
bun install
bun run build

build 脚本将 src/calendar-reader.swift 编译为 bin/calendar-reader。

MCP 客户端配置

Claude Code

claude mcp add --transport stdio ical --scope user -- bun run /absolute/path/to/mcp-ical-swift/src/index.ts

OpenClaw

{
  "mcp": {
    "servers": {
      "ical": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "ical": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
    }
  }
}

工具

工作原理

MCP Client (Claude, OpenClaw, etc.)
  --> stdio --> Bun MCP server (src/index.ts)
    --> execFileSync --> compiled Swift binary (bin/calendar-reader)
      --> EventKit framework --> Apple Calendar data

Swift 二进制文件被编译一次 (bun run build)，并在每次调用工具时同步执行。它将 JSON 输出到 stdout，Bun MCP 服务器将其包装在 MCP 工具结果中。服务器使用 execFileSync（而非 shell 执行）以避免注入风险。

关键点在于：swiftc 编译的二进制文件经过 Apple 签名，并从系统工具链继承了日历 TCC 权限。这绕过了阻止 Node、Bun、Python 和 AppleScript 在无头上下文中访问日历的 TCC 限制。

隐私与安全

• 此服务器默认访问系统上的所有日历（iCloud、Exchange、本地、共享、订阅）。您可以在 list_events 和 search_events 中使用可选的 calendar 参数按日历名称进行过滤。

• 事件备注会包含在响应中，可能包含敏感数据（会议 PIN 码、密码、个人详细信息）。在授予 MCP 客户端访问权限时请考虑这一点。

• 写操作（create_event、update_event、delete_event）无需确认步骤即可使用。MCP 客户端（或其中的提示词注入）可能会修改您的日历数据。

• 所有通信均通过 stdio 在本地进行 —— 不会向外部服务发送任何数据。

• 如需报告漏洞，请参阅 SECURITY.md。

限制

• 仅限 macOS（需要 EventKit 和 Swift 工具链）

• 需要 Bun 运行时

• Swift 二进制文件编译一次，并在每次工具调用时同步调用 —— 不适用于高吞吐量场景

• 循环事件的修改仅适用于单个实例 (.thisEvent 范围)

• 日历访问权限取决于 macOS TCC 是否授予了编译后的二进制文件权限

故障排除

"Calendar access is not granted" (未授予日历访问权限)

编译后的二进制文件需要至少在具有日历 TCC 权限的上下文中运行一次。运行构建并测试：

bun run build
bin/calendar-reader list-events $(date +%Y-%m-%d)

如果这返回了事件，则说明二进制文件具有日历访问权限。如果没有，请尝试从 Terminal.app（通常已授予日历 TCC 权限）运行。

事件为空

检查您是否在 Apple 日历中配置了日历。运行：

bin/calendar-reader list-calendars

编译失败

确保已安装 Xcode 命令行工具：

xcode-select --install

许可证

MIT