使用说明
苹果日历mcp
通过本地EventKit API为Apple Calendar提供MCP服务器，并提供适当的重复事件支持。
为什么存在
基于AppleScript的日历集成无法正确展开重复事件——它们返回的是主事件，而不是单个事件。该项目使用苹果的原生EventKit框架 predicateForEvents，它正确地将重复事件扩展为日期范围内的单个事件。
建筑
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}
先决条件
- macOS 13+（Ventura或更高版本）
- Swift 5.9+（Xcode 15+附带）
- Node.js 20+
安装
选项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
MCP工具
| 工具 | 说明 |
|---|---|
get_calendars |
列出所有日历及其ID和颜色 |
get_events |
获取日期范围内的事件（正确展开重复事件） |
get_today_events |
获取今天的所有活动 |
search_events |
按标题、位置或注释搜索事件 |
create_event |
创建新的日历事件 |
delete_event |
删除事件（单个事件或所有未来事件） |
验证
# Check system diagnostics
swift/.build/release/apple-bridge doctor
# List calendars
swift/.build/release/apple-bridge calendars
# Today's events
swift/.build/release/apple-bridge today
# Events in a date range (recurring events expanded)
swift/.build/release/apple-bridge events --start "2026-02-01T00:00:00Z" --end "2026-02-28T23:59:59Z"
故障排除
日历访问被拒绝 重置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验证构建 - 提交拉取请求