金大哥 - calendar-app-mcp MCP 详情

article

README

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

calendar-app-mcp