Calendar.app

calendar-mcp

MCP 服务，让 Claude（以及其他 MCP 宿主）能够全面访问 macOS 上的 Calendar.app，包括在 Calendar.app 中配置的所有账户（iCloud、Google、Exchange 等）中列出、搜索、创建、更新和删除日历事件。

前提条件

• macOS（需要 Calendar.app）
• Node.js 20+
• MCP 宿主：Claude Desktop 或任何 stdio MCP 客户端

安装

Claude Desktop — 一键安装（推荐）

1. 从最新版本下载 calendar-mcp.mcpb
2. 双击 .mcpb 文件，Claude Desktop 会自动安装
3. 授予所需的 macOS 权限（见下文）

手动安装／其他宿主

npx @p-l-ta/calendar-mcp

或进行全局安装：

npm install -g @p-l-ta/calendar-mcp
calendar-mcp

将 MCP 宿主指向 calendar-mcp 二进制文件（stdio 传输）。配置示例：

{
  "mcpServers": {
    "calendar-app": {
      "command": "npx",
      "args": ["@p-l-ta/calendar-mcp"]
    }
  }
}

所需的 macOS 权限

向运行 MCP 宿主的应用程序（Claude Desktop 等）授予以下权限：

权限	授权位置
完全磁盘访问权限	系统设置 → 隐私与安全性 → 完全磁盘访问权限
自动化 → Calendar	系统设置 → 隐私与安全性 → 自动化

MCP 服务进程会继承启动它的宿主应用程序的权限。

工具

工具	描述
list_calendars	列出所有日历及其名称、颜色、账户和 UUID
list_events	列出指定日期范围内的日历事件，包括重复事件的各次发生记录
get_event	根据 UUID 获取单个日历事件的完整详情，包括参与者
search_events	根据文本搜索日历事件，搜索范围包括标题、描述和地点
create_event	创建新的日历事件
update_event	更新现有日历事件的属性
delete_event	永久删除日历事件

工作原理

• 读取（list_calendars、list_events、search_events、get_event）——直接查询 Calendar 的 SQLite 数据库，以便快速获取结构化结果，覆盖所有账户。通过 Calendar 的 OccurrenceCache 表正确展开重复事件。
• 写入（create_event、update_event、delete_event）——通过针对 Calendar.app 的 AppleScript 自动化实现，因此更改会同步到所有已连接的账户（iCloud、Google、Exchange），就像在应用中进行操作一样。

开发

npm install
npm run dev          # tsx watch — live reload
npm run build        # compile TypeScript → dist/
npm run mcpb         # build Claude Desktop extension → build/calendar-mcp.mcpb
npm run smoke        # smoke-test all 7 tools against live Calendar.app data

注意： npm run smoke 需要 Terminal.app（或你的终端模拟器）拥有完全磁盘访问权限，因为它会直接读取 Calendar.sqlitedb。

交互式 MCP 测试：

npm run build
npx @modelcontextprotocol/inspector node dist/server.js

隐私政策

calendar-mcp 是一款完全在 Mac 上运行的本地 MCP 服务。它没有后端、不会收集遥测数据，也不会自行发起网络请求。

访问的内容：

• Calendar 的 SQLite 数据库（~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb）——只读，用于列表和搜索查询
• 通过 AppleScript 访问 Calendar.app——用于创建、更新和删除日历事件

不会执行的操作：

• 在 Mac 之外收集、存储或传输任何数据
• 连接任何外部服务或 API
• 在任何位置记录日历数据

所有日历数据都保留在你的设备上，仅作为正常工具响应的一部分传递给 MCP 宿主（Claude Desktop 或其他客户端）。你可以准确控制 Claude 能调用哪些工具。

许可证

MIT