Calendar 应用 MCP 服务器

一个提供 macOS Calendar.app 事件和提醒事项访问的 MCP (模型上下文协议) 服务器，适用于与 Claude 和其他 AI 助手集成。

MCP 集成

此包可以作为 MCP 服务器运行，以与 Claude 和支持 MCP 协议的其他 AI 助手集成，使它们能够访问和交互您的 macOS 日历数据。

# 作为 MCP 服务器为 AI 助手集成运行
uvx calendar-app-mcp   # 自动作为 MCP 服务器运行且无参数
uvx calendar-app-mcp mcp   # 显式运行 MCP 服务器

一旦运行，Claude 可以通过 MCP 协议与您的日历数据交互，允许它：

• 检查即将到来的事件
• 找到空闲时间段
• 查看事件详细信息
• 访问提醒事项
• 根据日历、日期范围等过滤事件

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：生成查看每日日程的提示

功能

• 访问 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]

运行测试

运行所有测试：

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

发布到 PyPI

要发布新版本到 PyPI：

1. 更新 pyproject.toml 中的版本号
2. 运行测试以验证一切正常：uv run pytest --black --ruff
3. 构建包：UV_NO_CONFIG=1 uv run python -m build
4. 上传到 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 文件。