Calendar App MCP

🚀 カレンダーアプリ MCP サーバー

このサーバーは、macOS Calendar.app のイベントとリマインダーにアクセスできる MCP（モデルコンテキストプロトコル）サーバーです。Claude や他の AI アシスタントとの統合に最適です。

🚀 クイックスタート

MCP 統合

このパッケージは、MCP サーバーとして実行でき、Claude や MCP プロトコルをサポートする他の AI アシスタントと統合して、macOS のカレンダーデータにアクセスし、やり取りすることができます。

# AI アシスタント統合用の MCP サーバーとして実行
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

利用可能なコマンド名

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

# 汎用カレンダーアプリケーションツール - 引数なしで実行するとヘルプが表示されます
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]

💻 使用例

基本的な使用法

# イベントを取得する
uvx calendar-app-mcp get_events --start-date 2024-01-01 --end-date 2024-01-31

高度な使用法

# 特定のカレンダーのイベントを取得する
uvx calendar-app-mcp get_events --start-date 2024-01-01 --end-date 2024-01-31 --calendar "Work"

テストの実行

すべてのテストを実行する

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 ファイルを参照してください。