MCP iCal Server

MCP iCal Server

このプロジェクトは Omar-V2/mcp-ical をベースに、エージェントベースのアプローチを用いてユーザーとのインタラクション層を再実装したものです。

🌟 概要

専用の AI エージェントを使って、macOS のカレンダーとのやり取りを一新しましょう！この MCP iCal サーバーは OpenAI Agent SDK を活用し、すべてのカレンダー操作を実行する、強力な単一のエントリーポイントを提供します。

複数のツールを公開する従来の MCP 実装とは異なり、このサーバーはエージェントベースのアプローチを採用しています。

• 🧠 単一のツールインターフェース：MCP ツール（send_to_calendar_agent）は 1 つだけで、専門のカレンダーエージェントに処理を委任します
• 🤖 状態を保持する会話：エージェントは、同じセッション内のリクエスト間でコンテキストを維持します
• 🔄 設定不要で動作：自然言語処理は専門のエージェントによって自動的に処理されます

You: "What's my schedule for next week?"
Claude: "Let me check that for you..."
[Calendar agent processes request and returns clean schedule]

You: "Add a lunch meeting with Sarah tomorrow at noon"
Claude: "Event created: Lunch with Sarah, tomorrow at 12:00 PM"

✨ 機能

📅 イベントの作成

自然言語からカレンダーイベントをすぐに作成できます！

"Schedule a team lunch next Thursday at 1 PM at Bistro Garden"
↓
📎 Created: Team Lunch
   📅 Thursday, 1:00 PM
   📍 Bistro Garden

対応機能：

• カレンダーの選択
• 場所とメモ
• スマートリマインダー
• 繰り返しイベント

パワーユーザー向けの例：

🔄 Recurring Events:
"Set up my weekly team sync every Monday at 9 AM with a 15-minute reminder"

📝 Detailed Events:
"Schedule a product review meeting tomorrow from 2-4 PM in the Engineering calendar, 
add notes about reviewing Q1 metrics, and remind me 1 hour before"

📱 Multi-Calendar Support:
"Add a dentist appointment to my Personal calendar for next Wednesday at 3 PM"

🔍 スマートなスケジュール管理と空き状況の確認

自然な言葉で問い合わせて、スケジュールをすばやく確認できます。

"What's on my calendar for next week?"
↓
📊 Shows your upcoming events with smart formatting

"When am I free to schedule a 2-hour meeting next Tuesday?"
↓
🕒 Available time slots found:
   • Tuesday 10:00 AM - 12:00 PM
   • Tuesday 2:00 PM - 4:00 PM

✏️ イベントのインテリジェントな更新

自然な言葉でイベントを変更できます。

"Move tomorrow's team meeting to 3 PM instead"
↓
✨ Meeting rescheduled to 3:00 PM

更新できる項目：

• 時刻と日付の変更
• カレンダー間の移動
• 場所の更新
• メモの追加
• リマインダーの調整
• 繰り返しパターンの変更

📊 カレンダー管理

• 利用可能なすべてのカレンダーを表示
• スマートなカレンダーの提案
• iCloud と連携している場合、Google Calendar とシームレスに統合

💡 ヒント：カスタムカレンダーにイベントを作成できるため、Google Calendar を iCloud Calendar と同期していれば、この MCP サーバーを使って Google Calendar にもイベントを作成できます！イベントの作成や更新時に、Google カレンダーを指定してください。

🚀 クイックスタート

💡 注：ここでは Claude for Desktop で MCP サーバーを設定する手順を説明していますが、このサーバーは MCP 対応クライアントであればどれでも使用できます。ほかのクライアントの使用方法について詳しくは、MCP のドキュメントをご覧ください。

前提条件

• uv パッケージマネージャー
• カレンダーアプリを設定済みの macOS
• MCP クライアント — Claude for desktopを推奨
• OpenAI API キー（OPENAI_API_KEY 環境変数として設定）

インストール

この MCP サーバーは MCP 対応クライアントであればどれでも使用できますが、以下の手順は Claude for desktop 向けです。

1. クローンとセットアップ

# Clone the repository
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical

# Install dependencies
uv sync

2. API キーを使って Claude for Desktop を設定

~/Library/Application\ Support/Claude/claude_desktop_config.json を作成または編集し、OpenAI API キーを環境変数として設定します。

{
    "mcpServers": {
        "mcp-ical": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
                "run",
                "mcp-ical"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key-here"
            }
        }
    }
}

3. カレンダーにアクセスするため Claude を起動

⚠️ 重要：カレンダーのアクセス許可を正しく要求するには、Claude をターミナルから起動する必要があります。Finder から直接起動した場合、アクセス許可を求めるプロンプトは表示されません。

/Applications/Claude.app/Contents/MacOS/Claude

4. 利用開始！

Try: "What's my schedule looking like for next week?"

🔑 注：カレンダー関連のコマンドを初めて使用すると、macOS によってカレンダーへのアクセス許可を求めるプロンプトが表示されます。このプロンプトは、上記の手順に従ってターミナルから Claude を起動した場合にのみ表示されます。

🧪 テスト

⚠️ 警告：テストでは一時的なカレンダーとイベントが作成されます。後片付けは自動的に行われますが、テストは開発環境でのみ実行してください。

# Install dev dependencies
uv sync --dev

# Run test suite
uv run pytest tests

🧠 仕組み

この実装では、独自のアーキテクチャを採用しています。

1. 1 つの MCP ツール（send_to_calendar_agent）をクライアントに公開します
2. 呼び出されると、このツールはリクエストを OpenAI Agent SDK で構築された専用のカレンダーエージェントに渡します
3. エージェントは自然言語によるリクエストを処理し、適切なカレンダー操作を呼び出します
4. 結果を整形してクライアントに返します

この方法には、いくつかの利点があります。

• クライアントとの統合を簡素化：呼び出すツールは 1 つだけです
• コンテキスト処理を改善：エージェントが会話の状態を維持します
• より自然なやり取り：専用エージェントがカレンダー固有の用語や意図を理解します

❓ このプロジェクトとオリジナルの違い

この実装では、Omar-V2/mcp-ical のカレンダー機能の中核を多く維持しながら、ユーザーとの対話レイヤーを全面的に再実装しています。

1. 単一のエントリーポイント：複数の MCP ツールをクライアントに直接公開する代わりに、OpenAI を利用したエージェントに処理を委ねる単一のエントリーポイントを実装しました
2. エージェントベースの処理：自然言語の理解とカレンダー操作への変換を担う OpenAI エージェントを追加しました
3. 状態を保持する会話：同じセッション内のリクエスト間で会話のコンテキストを追跡する機能を追加しました
4. クライアントとの統合を簡素化：クライアントが把握する必要のあるツールは、複数のカレンダー操作ではなく 1 つだけです

イベントの作成や一覧表示などのカレンダー操作の中核部分と macOS との統合は、オリジナルからほとんど変更されていません。

🐛 既知の問題

繰り返しイベント

• 標準外の繰り返しスケジュールは、正しく設定されない場合があります
• より高性能な LLM モデルを使うと、より良い結果が得られます
• 終日の繰り返しイベントのリマインダー時刻が、1 日ずれる場合があります

🤝 貢献

フィードバックや貢献を歓迎します。次の方法でご協力いただけます。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

📝 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

📝 謝辞

• オリジナルプロジェクト：Omar-V2 による Omar-V2/mcp-ical をベースにしています
• Model Context Protocol を使用して構築されています
• カレンダーとの統合には PyObjC を使用しています
• エージェント機能は OpenAI Agent SDK によって提供されています