Calendar App MCP

Calendar App MCP

Claude やその他の AI アシスタントで使用できるよう、macOS の Calendar.app のイベントとリマインダーへのアクセスを提供する MCP（Model Context Protocol）サーバーです。

MCP 連携

このパッケージは、MCP プロトコルに対応する Claude やその他の AI アシスタントと連携するために、MCP サーバーとして実行できます。これにより、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

利用可能なコマンド名

インストール後、このパッケージでは 2 つのコマンドライン実行ファイルを利用できます。

# 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