Calendar App MCP

Calendar App MCP

一个 MCP（Model Context Protocol）服务，可访问 macOS Calendar.app 中的事件和提醒，供 Claude 和其他 AI 助手使用。

MCP 集成

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

# Run as MCP server for AI assistant integration
uvx calendar-app-mcp   # Automatically runs as MCP server with no arguments
uvx calendar-app-mcp mcp   # Explicitly runs the MCP server

运行后，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
• 安全地在本地访问日历数据

安装

# Install from PyPI
pip install calendar-app-mcp

# Using uv
uv pip install calendar-app-mcp

# Using uvx (direct execution without installation)
uvx calendar-app-mcp calendars
uvx calendar-app-mcp mcp

可用命令名称

安装后，此软件包会提供两个命令行可执行文件：

# General-purpose calendar app tool - shows help when run without arguments
calendar-app

# MCP-focused variant - defaults to running the MCP server when no arguments are provided
calendar-app-mcp

两个命令都支持相同的子命令，但 calendar-app-mcp 针对作为 MCP 服务使用进行了优化。

开发环境安装

# Clone the repository
git clone https://github.com/rygwdn/calendar-app-mcp.git
cd calendar-app-mcp

# Install uv package manager if not already installed
# https://github.com/astral-sh/uv

# Install the package in development mode
uv install -e .

# Install with development dependencies (for testing)
uv install -e '.[dev]'

CLI 用法

除了作为 MCP 服务运行外，此软件包还可用作命令行工具，直接访问日历数据：

# List available calendars
uvx calendar-app-mcp calendars

# Get today's events and reminders
uvx calendar-app-mcp today

# Get only events
uvx calendar-app-mcp events

# Get only reminders
uvx calendar-app-mcp reminders

# Get both events and reminders
uvx calendar-app-mcp all

# Show JSON schema
uvx calendar-app-mcp schema

# Check version
uvx calendar-app-mcp --version
# or 
uvx calendar-app-mcp version

命令选项

大多数子命令都接受以下选项：

# Output in JSON format (default is markdown)
uvx calendar-app-mcp events --json

# Filter by date range
uvx calendar-app-mcp events --from 2024-12-01 --to 2024-12-31

# Filter by specific calendars
uvx calendar-app-mcp events --calendars "Work" "Personal"

# Only show all-day events
uvx calendar-app-mcp events --all-day-only

# Only show busy events
uvx calendar-app-mcp events --busy-only

# Include completed reminders
uvx calendar-app-mcp reminders --include-completed

开发

使用 UV 和公共 PyPI 注册表

为确保 UV 使用公共 PyPI 注册表，而不是本地配置的任何仓库：

# Generate a lock file using only PyPI
UV_NO_CONFIG=1 uv lock

# Install dependencies using only PyPI
UV_NO_CONFIG=1 uv install

UV_NO_CONFIG=1 环境变量会告知 UV 忽略所有系统级配置，仅使用公共 PyPI 注册表。

发布到 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 文件。

运行测试

运行所有测试：

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