Apple Calendar MCP

Apple Calendar MCP 是一个本地优先的 Model Context Protocol 服务器，用于将 AI 助手安全地连接到 macOS 上的 Apple Calendar。

它使用了 TypeScript MCP 服务器、Swift EventKit 辅助程序、SQLite 本地状态和原生 macOS 设置应用。日历数据保留在 Mac 上，用户可以选择哪些日历可见，写入操作则受权限模式、确认门控、重复检查、幂等性、回滚记录、审计日志和变更订阅的保护。

主要功能

• 通过 MCP 工具读取 Apple Calendar 中的日历、事件、可用性和权限。

• 创建、更新、改期和删除事件，并默认启用 preview-confirm 安全机制。

• 在服务端强化日历允许列表，使被阻止的日历对代理保持不可见。

• 跟踪回滚记录、审计记录、紧凑快照和 token 高效的变更订阅。

• 为 Claude Desktop、Codex、Cursor、OpenClaw 和通用 MCP 客户端生成客户端配置。

• 提供原生 macOS 设置向导，用于日历授权、允许列表、权限模式、配置生成和验证。

Related MCP server: nucleus-apple-mcp

架构

flowchart TD
  A["MCP Client<br/>Claude, Codex, Cursor, OpenClaw"] --> B["TypeScript MCP Server"]
  B --> C["Calendar Service Layer"]
  C --> D["Swift EventKit Helper"]
  D --> E["Apple Calendar / EventKit"]
  C --> F["SQLite Local State"]
  F --> G["Config, Audit, Rollback,<br/>Snapshots, Change Feed,<br/>Idempotency"]
  H["Native macOS Setup App"] --> D
  H --> F

MCP 服务器通过 stdio 通信。日志写入 stderr 或可选的本地日志文件，绝不写入 stdout，从而保持 MCP 协议流量干净。

系统要求

• 支持 Apple Calendar 和 EventKit 访问的 macOS。

• Node.js >=22.5。

• 通过 Xcode Command Line Tools 或 Xcode 安装的 Swift 工具链。

• MCP 客户端，如 Claude Desktop、Codex、Cursor、OpenClaw 或其他兼容 stdio 的客户端。

从源代码安装

git clone <repo-url>
cd apple-calendar-mcp
npm install
npm run build
npm run helper:bundle
npm run helper:setup

设置应用会逐步引导您完成：

1. Assessment Calendar 权限：

2. 选择日历允许列表。

3. 选择权限模式。

4. 生成 MCP 客户端配置。

5. 执行验证检查和测试连接。

生成的本地配置存储于：

~/Library/Application Support/AppleCalendarMCP/

MCP 客户端设置

生成经过验证的客户端配置：

npm run client-configs:generate

Skip the merge of the file generated from .generated/client-configs/ into your client：

• Claude Desktop：claude_desktop_config.json

• Codex：将 codex.config.toml 追加到 ~/.codex/config.toml

• Cursor：将 cursor.mcp.json 复制或合并到 ~/.cursor/mcp.json 或项目的 .cursor/mcp.json

• OpenClaw：将 openclaw.openclaw.json 合并到 ~/.openclaw/openclaw.json

• 通用 MCP 客户端应使用 generic-mcp-client.json

复制后执行验证：

npm run client-configs:validate
npm run client-configs:diagnose

生成的配置使用绝对路径的 Node 可执行文件、绝对路径的 MCP 服务器入口点和 env 块。命令和参数绝不会组合为 shell 字符串，这样可避免包含空格的路径导致失败。

npx 启动方式

可发布的服务器包暴露以下 binary：

npx apple-calendar-mcp

对于本地开发和预发布版本，优先使用：

npm run start:mcp

在发布到 npm 之前，请按依赖顺序发布内部工作区包，或使用 npm run release:package 生成的发布产物。

安全模型

Apple Calendar MCP 围绕纵深防御进行设计：

• 访问 EventKit 之前，必须先获得 macOS Calendar 权限。

• 日历允许列表会限制代理程序可以查看的日历。

• 只读（read-only）、写前询问（ask-before-write）、受信任写入（trusted-write）和完全写入（full-write）模式来控制写入风险。

• MVP 写入需要明确的确认或 preview-confirm 流程。

• 破坏性和歧义操作会返回语义错误，而不是进行猜测。

• 周期事件的写入需要明确指定范围。

• 日历内容被视为不受信任的输入。

• 审计记录、回滚记录、幂等性键和变更订阅会写入本地。

完整安全模型请参见 docs/Security Specification.md。

屏幕截图

发布版截图占位：

• 设置向导欢迎页和 Calendar 权限步骤。

• Calendar 允许列表和权限模式步骤。

• 客户端配置和验证步骤。

• 设置和诊断界面。

在公开分发之前，请截取签名发布版的屏幕截图。

故障排查

• Calendar 访问被保护：打开告知系统设置 > 隐私与安全 > 日历，然后启用辅助 App。

• 在设置中 MCP 服务器启动显示：运行 npm run build，并确认 packages/mcp-server/dist/index.js 存在。

• Cursor 或 Codex 无法连接：使用 npm run client-configs:generate 重新生成配置，并确保复制后的配置使用绝对路径。

• 客户端看到服务器但没有工具时：配置变更后重启 MCP 客户端，然后运行 npm run client-configs:diagnose。

• stdout/stderr 分离失败：请从 MCP 服务器路径上移除任何 stdout 日志；日志必须写入 stderr。

• 读取文件过大失败：请使用更窄的日期范围。读取服务会在内部对较大的窗口进行分块，但非常大的 EventKit 请求可能仍需要重试。

开发

npm install
npm run build
npm test
npm run helper:bundle
npm run helper:setup

常用命令：

• npm run typecheck

• npm run client-configs:generate

• npm run client-configs:validate

• npm run release:verify

• npm run release:package

在做出影响安全性的更改之前，请先阅读 docs/Development Guide.md。

仓库结构

apps/macos-helper/        Swift EventKit bridge and native setup app
packages/mcp-server/      MCP stdio server and tool registration
packages/calendar-service/Business logic for reads, writes, rollback, snapshots
packages/sqlite-store/    Local SQLite persistence and migrations
packages/shared/          Shared schemas and typed contracts
scripts/                  Helper, config, diagnostics, and release scripts
tests/                    Phase-based safety and behavior tests
docs/                     Consolidated maintainer and release documentation

发布

创建可复现的本地发布产物：

npm run release:package

构建产物和校验信息将写入：

dist/release/

GitHub 发布工作流会在匹配 v* 的标签推送时运行相同的打包脚本。

路线图

• 签名并已公证的 macOS 发布打包。

• 在确定软件包命名空间后，提供公开 npm 发布工作流。

• 在更多受支持的 MCP 客户端中运行端到端冒烟测试。

• 扩展快照/变更订阅分页基准测试。

• 改进应用内截图捕获和公共文档素材。

贡献指南

安全、可靠性、用户信任、MCP 合规性和可维护性优先于便利性。请保持更改范围清晰，运行完整测试套件，并在行为发生变更时更新文档。不要绕过权限检查、允许列表、确认门控、回滚记录、审计记录、幂等性检查和语义错误。

从这些文档开始：

• docs/Product Specification.md

• docs/Technical Specification.md

• docs/Security Specification.md

• docs/Development Guide.md

• docs/Installation Guide.md

• docs/Release Checklist.md