金大哥 - macos-calendar-mcp MCP 详情

article

README

🚀 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 预装）

📦 安装指南

克隆仓库：

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

安装依赖：

npm install

授予权限：
- 首次运行时，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

📚 详细文档

可用工具

| 工具 | 描述 | 参数 | |------|-------------|------------| | list-calendars | 列出所有可用日历 | 无 | | create-event | 创建新的日历事件 | title、startDate、endDate、calendar、description、location | | list-today-events | 列出今天的事件 | calendar（可选） | | search-events | 按关键字搜索事件 | query、calendar（可选） |

💻 使用示例

基础用法

创建事件：

{
  "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 等）

故障排除

权限问题

若遇到权限错误：

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

AppleScript 错误

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

时区问题

若事件显示时间错误：

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

🔧 技术细节

贡献方式

分叉仓库。
创建功能分支。
进行更改。
在 macOS 上进行全面测试。
提交拉取请求。

为何选择此 MCP

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

✅ 无需配置即可立即使用。
✅ 与现有的 macOS 日历设置集成。
✅ 支持所有日历源（如 iCloud、Google、Exchange 等）。
✅ 基本操作无需互联网连接。
✅ 尊重隐私 - 所有操作均在本地运行。

非常适合希望在不使用 OAuth 的情况下集成日历的开发者！

隐私与安全

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

数据保护

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

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

📄 许可证

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

macos-calendar-mcp