Calendar App MCP

一個MCP協議服務器，用於讓AI助手（如Claude）訪問和交互macOS日曆應用的事件和提醒事項。

日程管理人工智能聊天機器人 #日曆管理 #AI集成 #本地訪問 #時間管理 .Python

評分 : 2.5分

下載量 : 20

更新時間 : 2025-04-29

什麼是Calendar App MCP?

這是一個運行在您電腦上的本地服務，作為AI助手(如Claude)與macOS日曆應用之間的安全橋樑。它允許AI助手在獲得您許可的情況下，幫助管理您的日程安排。

如何使用Calendar App MCP?

只需簡單安裝後運行服務，當AI助手需要訪問您的日曆時，會通過這個安全通道獲取信息，所有數據都保留在您的設備上。

適用場景

當您需要AI助手幫助安排會議、查看空閒時間、提醒重要事件或整理日常行程時特別有用。

主要功能

日曆事件訪問安全讀取macOS日曆中的事件信息，包括時間、地點和詳情

提醒事項集成獲取macOS提醒事項的內容和狀態

時間管理工具查找空閒時間段、轉換時區和獲取當前時間

智能篩選按日期範圍、日曆類型和忙碌狀態篩選事件

優勢與侷限性

優勢

完全本地運行，數據不會離開您的設備

支持豐富的查詢條件和篩選選項

簡單易用的命令行界面

與主流AI助手無縫集成

侷限性

僅支持macOS系統

需要Python環境運行

首次配置可能需要技術基礎

如何使用

安裝服務

通過Python包管理器安裝日曆MCP服務

啟動服務

運行MCP服務器以允許AI助手訪問

連接AI助手

在AI助手界面啟用MCP集成功能

使用案例

安排會議讓AI助手幫您找出下週合適的會議時間

每日簡報獲取當天重要事件和任務的概覽

跨時區協調與國際團隊協調會議時間

常見問題

我的日曆數據安全嗎？

支持哪些AI助手？

需要哪些系統權限？

如何更新服務？

🚀 日曆應用 MCP 服務器

這是一個 MCP（模型上下文協議）服務器，可提供對 macOS Calendar.app 事件和提醒事項的訪問，適用於與 Claude 及其他 AI 助手集成，幫助用戶更便捷地管理和利用日曆數據。

🚀 快速開始

此包可作為 MCP 服務器運行，與 Claude 及支持 MCP 協議的其他 AI 助手集成，讓它們能夠訪問和交互您的 macOS 日曆數據。

# 作為 MCP 服務器為 AI 助手集成運行
uvx calendar-app-mcp   # 自動作為 MCP 服務器運行且無參數
uvx calendar-app-mcp mcp   # 顯式運行 MCP 服務器

運行後，Claude 可通過 MCP 協議與您的日曆數據交互，實現以下功能：

檢查即將到來的事件
找到空閒時間段
查看事件詳細信息
訪問提醒事項
根據日曆、日期範圍等過濾事件

✨ 主要特性

可訪問 macOS Calendar.app 事件和提醒事項。
支持根據日期範圍、日曆名稱和全天/忙碌狀態進行過濾。
支持以 JSON 或 Markdown 格式輸出。
可安全本地訪問日曆數據。

📦 安裝指南

常規安裝

# 從 PyPI 安裝
pip install calendar-app-mcp

# 使用 uv
uv pip install calendar-app-mcp

# 使用 uvx（無需安裝直接執行）
uvx calendar-app-mcp calendars
uvx calendar-app-mcp mcp

可用命令名稱

安裝後，該包提供兩個命令行可執行文件：

# 通用日曆應用工具 - 無參數運行時顯示幫助
calendar-app

# 以 MCP 為中心的變體 - 默認情況下無參數運行時啟動 MCP 服務器
calendar-app-mcp

兩者支持相同的子命令，但 calendar-app-mcp 更適合用作 MCP 服務器。

開發安裝

# 克隆倉庫
git clone https://github.com/rygwdn/calendar-app-mcp.git
cd calendar-app-mcp

# 如果尚未安裝，請安裝 uv 包管理器
# https://github.com/astral-sh/uv

# 以開發模式安裝包
uv install -e .

# 使用測試依賴項進行安裝（可選）
uv install -e .[tests]

💻 使用示例

基礎用法

# 作為 MCP 服務器為 AI 助手集成運行
uvx calendar-app-mcp   # 自動作為 MCP 服務器運行且無參數
uvx calendar-app-mcp mcp   # 顯式運行 MCP 服務器

高級用法

# 運行特定測試文件
python -m pytest tests/unit/utils/test_date_utils.py

# 運行特定測試
python -m pytest tests/unit/utils/test_date_utils.py::TestParseDate::test_valid_date

📚 詳細文檔

MCP 工具和資源

此包提供了多個 MCP 工具和資源：

工具

get_events：檢索特定日期範圍的事件
get_reminders：檢索特定日期範圍的提醒事項
list_calendars：列出所有可用日曆
get_today_summary：獲取今天事件和提醒事項的摘要
search：搜索包含特定術語的事件和提醒事項
get_current_time：獲取指定時區的當前日期和時間
convert_time：將一個時區的時間轉換為另一個時區
list_timezones：列出所有可用時區，可選按區域過濾

資源

calendar://events/{date}：訪問特定日期的事件
calendar://calendars：訪問可用日曆列表
datetime://current/{timezone}：獲取指定時區的當前時間

提示

daily_agenda：生成查看每日日程的提示

發佈到 PyPI

要發佈新版本到 PyPI，可按以下步驟操作：

更新 pyproject.toml 中的版本號。
運行測試以驗證一切正常：uv run pytest --black --ruff。
構建包：UV_NO_CONFIG=1 uv run python -m build。
上傳到 PyPI：

UV_NO_CONFIG=1 uv run twine upload dist/calendar_app_mcp-X.Y.Z*

將 X.Y.Z 替換為實際版本號。 5. 驗證包是否可以安裝：uvx calendar-app-mcp@latest --version。 6. 創建並推送版本標籤：git tag vX.Y.Z && git push origin vX.Y.Z。

有關詳細說明，請參閱 CLAUDE.md 文件。

🔧 技術細節

運行測試相關的技術細節：

運行所有測試：python -m pytest。
生成覆蓋率報告：python -m pytest --cov=calendar_app。
運行特定測試文件：python -m pytest tests/unit/utils/test_date_utils.py。
運行特定測試：python -m pytest tests/unit/utils/test_date_utils.py::TestParseDate::test_valid_date。