🚀 日历应用 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。