Che Ical MCP

🚀 che-ical-mcp

che-ical-mcp 是一款適用於 macOS 的日曆與提醒事項 MCP 服務器，它通過原生的 EventKit 集成，為用戶提供了全面的日曆和任務管理功能。

English | 繁體中文

🚀 快速開始

針對 Claude Desktop

選項 A：MCPB 一鍵安裝（推薦）

從 Releases 下載最新的 .mcpb 文件，然後雙擊安裝。

選項 B：手動配置

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

{
  "mcpServers": {
    "che-ical-mcp": {
      "command": "/usr/local/bin/che-ical-mcp"
    }
  }
}

針對 Claude Code (CLI)

# 若需要，創建 ~/bin 目錄
mkdir -p ~/bin

# 下載最新版本
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# 添加到 Claude Code
# --scope user    : 可在所有項目中使用（存儲在 ~/.claude.json 中）
# --transport stdio: 通過 stdin/stdout 進行本地二進制執行
# --              : Claude 選項和命令之間的分隔符
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

💡 使用建議：始終將二進制文件安裝到本地目錄，如 ~/bin/。避免將其放置在雲同步文件夾（Dropbox、iCloud、OneDrive）中，因為文件同步操作可能會導致 MCP 連接超時。

從源代碼構建（可選）

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
swift build -c release

首次使用時，macOS 會提示請求 日曆 和 提醒事項 的訪問權限，請點擊“允許”。

✨ 主要特性

📦 安裝指南

安裝要求

• macOS 13.0 或更高版本
• Xcode 命令行工具（僅在從源代碼構建時需要）

針對 Claude Desktop

方法 1：MCPB 一鍵安裝（推薦）

1. 從 Releases 下載 che-ical-mcp.mcpb 文件。
2. 雙擊 .mcpb 文件進行安裝。
3. 重啟 Claude Desktop。

方法 2：手動配置

1. 下載二進制文件：

curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o /usr/local/bin/che-ical-mcp
chmod +x /usr/local/bin/che-ical-mcp

2. 編輯 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

{
  "mcpServers": {
    "che-ical-mcp": {
      "command": "/usr/local/bin/che-ical-mcp"
    }
  }
}

3. 重啟 Claude Desktop。

針對 Claude Code (CLI)

# 若需要，創建 ~/bin 目錄
mkdir -p ~/bin

# 下載二進制文件
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# 向 Claude Code 註冊（用戶範圍 = 可在所有項目中使用）
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

從源代碼構建（可選）

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
swift build -c release

# 複製到 ~/bin 並註冊
cp .build/release/CheICalMCP ~/bin/
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

授予權限

首次使用時，macOS 會提示請求 日曆 和 提醒事項 的訪問權限，請點擊“允許”。

⚠️ 重要提示

macOS Sequoia (15.x) 注意事項：權限對話框歸因於啟動 MCP 服務器的 父應用程序，而不是二進制文件本身。這意味著：

環境	權限歸因於
Claude Desktop	Claude Desktop.app ✅（自動生效）
在 Terminal.app 中使用 Claude Code	Terminal.app ✅（自動生效）
在 VS Code 中使用 Claude Code	VS Code ❌（可能不顯示對話框）
在 iTerm2 中使用 Claude Code	iTerm2 ✅（自動生效）

如果權限對話框未出現（常見於 VS Code），你需要在 VS Code 的 Info.plist 中添加 NSCalendarsFullAccessUsageDescription：

# 向 VS Code 添加日曆使用說明
/usr/libexec/PlistBuddy -c "Add :NSCalendarsFullAccessUsageDescription string 'VS Code needs calendar access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :NSRemindersFullAccessUsageDescription string 'VS Code needs reminders access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"

# 重新簽名 VS Code（修改 Info.plist 後需要）
codesign -s - -f --deep "/Applications/Visual Studio Code.app"

# 重啟 VS Code，權限對話框將出現

注意：此修改在 VS Code 更新時會被覆蓋。每次 VS Code 更新後，你需要重新應用此修改。

💻 使用示例

日曆管理

"列出我所有的日曆"
"我下週的日程安排是什麼？"
"創建一個明天下午 2 點的會議，標題為 '團隊同步'"
"添加一個週五上午 10 點的牙醫預約，地點為 '主街 123 號'"
"刪除名為 '已取消會議' 的會議"

提醒事項管理

"列出我未完成的提醒事項"
"顯示我購物清單中的所有提醒事項"
"添加一個提醒：購買牛奶"
"創建一個明天下午 5 點給媽媽打電話的提醒"
"將 '購買牛奶' 標記為已完成"
"刪除關於雜貨的提醒"

高級功能（v0.3.0+）

"搜索包含 '會議' 的事件"
"搜索同時包含 '項目' 和 '評審' 的事件"
"我今天有什麼安排？"
"顯示我本週的日程安排"
"如果我安排一個下午 2 點到 3 點的會議，是否有衝突？"
"為接下來的 3 周創建 3 個每週團隊會議"
"將牙醫預約複製到我的工作日曆"
"將 '舊日曆' 中的所有事件移動到 '新日曆'"
"刪除所有已取消的事件"
"查找 'IDOL' 和 'Idol' 日曆之間的重複事件"

開發者體驗改進（v1.0.0）

"顯示我接下來的 5 個即將到來的事件"
→ list_events(start_date: "2026-02-06", end_date: "2026-12-31", filter: "future", sort: "asc", limit: 5)

"顯示我逾期的提醒事項"
→ list_reminders(filter: "overdue")

"預覽在 2025 年之前從 '舊日曆' 中刪除哪些事件"
→ delete_events_batch(calendar_name: "Old Calendar", before_date: "2025-01-01", dry_run: true)

"創建一個下午 2 點的事件"（無需完整的 ISO8601 格式！）
→ create_event(start_time: "14:00", end_time: "15:00", ...)

📚 詳細文檔

支持的日曆源

該工具可與任何同步到 macOS 日曆應用的日曆配合使用：

• iCloud 日曆
• Google 日曆
• Microsoft Outlook/Exchange
• CalDAV 日曆
• 本地日曆

同名日曆區分（v0.6.0+）

如果你有來自不同源的同名日曆（例如，iCloud 和 Google 中都有“工作”日曆），可以使用 calendar_source 參數：

"在我的 iCloud 工作日曆中創建一個事件"
→ create_event(calendar_name: "Work", calendar_source: "iCloud", ...)

"顯示我的 Google 工作日曆中的事件"
→ list_events(calendar_name: "Work", calendar_source: "Google", ...)

如果檢測到歧義，錯誤消息將列出所有可用的源。

故障排除

🔧 技術細節

• 當前版本：v1.3.1
• 框架：MCP Swift SDK v0.11.0
• 日曆 API：EventKit（原生 macOS 框架）
• 傳輸方式：stdio
• 平臺：macOS 13.0+（Ventura 及更高版本）
• 工具：提供 25 個工具，用於日曆、事件、提醒事項、標籤和高級操作

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

貢獻說明

歡迎貢獻代碼！請隨時提交拉取請求。

作者

由 Che Cheng (@kiki830621) 創建。

如果你覺得這個項目有用，請給它點個星！