Macos Calendar MCP

🚀 macOS Calendar MCP Server

macOS Calendar MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，借助 AppleScript 实现与 macOS 日历的无缝集成，无需进行 OAuth 配置！

✨ 主要特性

• 🍎 原生 macOS 集成：利用 AppleScript 直接与 macOS 日历进行交互。
• 📅 全面的日历管理：可创建、列出和搜索日历事件。
• 🚀 零配置：无需 OAuth 和 API 密钥，开箱即用。
• 🔧 MCP 兼容：可与 Claude Code CLI 及其他 MCP 客户端配合使用。
• 📱 多日历支持：支持所有类型的日历（如个人、工作等）。

📦 安装指南

前提条件

• macOS（需支持 AppleScript）
• Node.js 16 及以上版本
• 日历应用（macOS 预装）

安装步骤

1. 克隆仓库：

git clone https://github.com/xybstone/macos-calendar-mcp.git
cd macos-calendar-mcp

2. 安装依赖：

npm install

3. 授予权限：
   • 首次运行时，macOS 会请求日历应用权限。
   • 授予访问权限，以便 MCP 服务器管理你的日历。

💻 使用示例

与 Claude Code CLI 配合使用

在 .claude_project 文件中添加以下内容：

{
  "mcpServers": {
    "macos-calendar": {
      "command": "node",
      "args": ["/path/to/macos-calendar-mcp/macos-calendar-mcp.js"]
    }
  }
}

或者直接运行：

node macos-calendar-mcp.js

可用工具

示例代码

基础用法

// 创建一个事件
{
  "title": "Team Meeting",
  "startDate": "2025-07-05 14:00",
  "endDate": "2025-07-05 15:00", 
  "calendar": "Work",
  "description": "Weekly team sync",
  "location": "Conference Room A"
}

高级用法

// 列出所有可用日历
// Returns all available calendars

// 搜索事件
{
  "query": "meeting",
  "calendar": "Work"
}

日期格式

使用 YYYY-MM-DD HH:MM 格式（24 小时制）。 示例：

• 2025-07-05 14:00（下午 2:00）
• 2025-12-25 09:30（上午 9:30）
• 2025-07-10 18:00（下午 6:00）

时区处理：

• 使用原生 macOS 时间处理，避免时区转换问题。
• 所有时间均按系统本地时区解释。
• 无需进行 UTC 转换或夏令时调整。

📚 详细文档

支持的日历

该服务器支持所有 macOS 日历，包括：

• 个人日历
• 工作日历
• 共享日历
• 订阅日历（如 iCloud、Google 等）

故障排除

权限问题

若遇到权限错误：

1. 打开“系统偏好设置”→“隐私与安全性”→“隐私”。
2. 从左侧边栏选择“日历”。
3. 确保“终端”（或你的应用）具有访问权限。

AppleScript 错误

• 确保日历应用已安装且可访问。
• 检查日历名称是否正确（区分大小写）。
• 验证日期格式是否符合预期模式。

时区问题

若事件显示时间错误：

1. 检查系统时区设置。
2. 使用 fix-event-times 工具纠正现有事件。
3. 确保日期格式为 YYYY-MM-DD HH:MM（24 小时制）。
4. MCP 使用原生 macOS 时间处理，避免转换问题。

贡献代码

1. 分叉仓库。
2. 创建功能分支。
3. 进行修改。
4. 在 macOS 上进行全面测试。
5. 提交拉取请求。

隐私与安全

• ✅ 本地处理：所有日历操作均在本地机器上运行。
• ✅ 无数据上传：你的日历数据不会离开设备。
• ✅ 注重隐私：无需 OAuth 令牌、无云服务、无跟踪。
• ⚠️ 私人数据：测试时，避免将包含个人事件的文件提交到公共仓库。

数据保护

项目包含 .gitignore 规则，防止意外提交私人事件数据：

• *events*.json - 事件数据文件
• *meetings*.json - 会议时间表
• *schedule*.json - 日程文件
• private-*.json - 任何私人数据文件

为什么选择这个 MCP？

与需要复杂 OAuth 配置的 Google Calendar 集成不同，此 MCP：

• ✅ 无需配置，立即使用。
• ✅ 与现有的 macOS 日历设置集成。
• ✅ 支持所有日历源（如 iCloud、Google、Exchange 等）。
• ✅ 基本操作无需互联网连接。
• ✅ 尊重隐私 - 一切都在本地运行。 非常适合希望在不涉及 OAuth 麻烦的情况下实现日历集成的开发者！

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。