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 文件。