AI导哈

日历应用MCP服务器

一个提供访问macOS日历应用事件和提醒的MCP服务器，用于与Claude等AI助手集成。

  • by rygwdn
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 rygwdn/calendar-app-mcp

使用说明

日历应用程序MCP

MCP（模型上下文协议）服务器，提供对macOS Calendar.app事件和提醒的访问，供Claude和其他AI助手使用。

MCP集成

此软件包可以作为MCP服务器运行，与支持MCP协议的Claude和其他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

发展

在公共PyPI注册表中使用UV

为确保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

相关 MCP