Calendar App MCP

一个MCP协议服务器，用于让AI助手（如Claude）访问和交互macOS日历应用的事件和提醒事项。

日程管理人工智能聊天机器人 #日历管理 #AI集成 #本地访问 #时间管理 .Python

评分 : 2.5分

下载量 : 22

更新时间 : 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。