icloud-calendar-mcp

iCloud Calendar MCP サーバー

AI アシスタントが CalDAV 経由で iCloud Calendar にアクセスできるようにする MCP（Model Context Protocol）サーバーです。OWASP MCP Top 10 に準拠したセキュリティ制御を備えています。

注意

メインの Apple ID パスワードは絶対に使用しないでください。 このサーバーにはアプリ用パスワードが必要です。アプリ用パスワードは Apple ID に影響を与えることなく個別に無効化できます。

このサーバーの特長

• 移植性の高い CalDAV。 JVM が動作する環境であればどこでも実行できます。macOS、AppleScript、Calendar.app に依存しません。
• 永続的なイベントハンドル。 get_events と create_event は、セッション間やプロセスの再起動後もイベントを参照できる不透明な handle を返します。そのため、イベントの編集や削除のたびに一覧を再取得する必要はありません。
• 正確な繰り返し処理。 範囲内の各発生につき 1 件の結果を返します。また、単一の発生分、この発生分と今後の分、またはシリーズ全体を編集・削除できます。
• 制限付きの応答。 日付範囲とイベント数に上限を設けており、応答を黙って切り詰めるのではなく、明確で構造化されたエラーを返します。
• 専用のテストスイートにより、OWASP MCP Top 10 に準拠したセキュリティを実現しています。
• MCP Registry、npm、PyPI で公開されています。

機能

MCP ツール

MCP リソース

MCP プロンプト

ユーザーが開始するテンプレートで、複数ステップのタスクを Claude が進めるためのガイドとして使用します。

セキュリティ機能

• 認証情報の保護 - 環境変数のみを使用し、コードや設定ファイルには保存しません
• 入力の検証 - SSRF 対策を含め、すべてのパラメーターを検証します
• レート制限 - MCP の仕様に基づき、読み取りは 1 分あたり 60 回、書き込みは 1 分あたり 20 回に制限します
• 安全なエラー処理 - エラーメッセージから機密データが漏えいしません
• OWASP MCP Top 10 への準拠 - 主要なリスクすべてを対象とする 282 件のセキュリティテスト
• ReDoS 対策 - すべての正規表現パターンを壊滅的なバックトラッキングに対してテストしています
• Unicode セキュリティ - ホモグリフ攻撃やエンコーディング攻撃への対策

クイックスタート

前提条件

• Java 21 以降（すべてのインストール方法で必要）
• アプリ用パスワードを設定した iCloud アカウント

インストール

お好みのインストール方法を選択してください。

重要

どの方法でも、同じ Java ビルドが実行されます。npx と uvx を使用する場合も含め、Java 21 以降が PATH に設定されている必要があります。 これらのラッパーは JAR をダウンロードして起動するものであり、JVM に代わるものではありません。

オプション 1：npm（推奨）

npx @icloud-calendar-mcp/server

オプション 2：Python（uvx）

uvx icloud-calendar-mcp

オプション 3：JAR を直接使用

# Download the latest release (version-agnostic name, always resolves)
curl -LO https://github.com/icloud-calendar-mcp/icloud-calendar-mcp/releases/latest/download/icloud-calendar-mcp-all.jar

# Run
java -jar icloud-calendar-mcp-all.jar

オプション 4：ソースからビルド

git clone https://github.com/icloud-calendar-mcp/icloud-calendar-mcp.git
cd icloud-calendar-mcp
./gradlew fatJar
java -jar build/libs/icloud-calendar-mcp-*-all.jar

設定

iCloud の認証情報を環境変数として設定します。

export ICLOUD_USERNAME="[email protected]"
export ICLOUD_PASSWORD="your-app-specific-password"

セキュリティに関する注意：メインの Apple ID パスワードではなく、App 用パスワードを使用してください。

Claude Desktop との連携

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["@icloud-calendar-mcp/server"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "java",
      "args": ["-jar", "/path/to/icloud-calendar-mcp-all.jar"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

使用例

設定が完了したら、Claude に次のように尋ねることができます。

• 「今週のカレンダーには何が入っていますか？」
• 「明日の午後 2 時に John との会議を作成して」
• 「すべてのカレンダーを表示して」
• 「金曜日の歯医者の予約を削除して」
• 「午後 3 時の会議を午後 4 時に移動して」

ツールのパラメーター

list_calendars

パラメーターは必要ありません。

get_events

知っておくべき動作：

• UTC の日付境界。 start_date と end_date は、UTC の暦日全体を指定します。範囲は start_date の UTC 00:00 から end_date の UTC 終了時までです。時刻指定のあるイベントでは、UTC の時点を示す startTime／endTime が返されます。終日イベントでは、通常の YYYY-MM-DD が返されます。別のタイムゾーンでのユーザーの 1 日を判定するには、前後にそれぞれ 1 日分余分にリクエストし、開始時刻をそのタイムゾーンに変換したときに対象の日付となるイベントを残してください。終日イベントはタイムゾーンに依存しない日付であるため、変換は不要です。
• 上限。 範囲は 366 日までで、end_date を start_date より前にすることはできません。応答は 1000 件までです。また、展開すると上限を超える単一の繰り返しシリーズは拒否されます。上限に達した場合は、1 週間または 1 か月ごとにクエリしてください。
• 繰り返しシリーズ。 範囲内の各回が個別の結果として返され、それぞれ固有の handle と、インスタンスを識別する recurrenceId が付与されます。
• 書き込み後の読み取り。 iCloud は即時反映を保証しないため、作成直後のイベントが次の get_events で短時間表示されないことがあります。これは CDN のインデックス作成の遅延であり、削除されたわけではないため、再作成しないでください。

各結果には、uid、handle、summary、isAllDay のほか、時刻指定のあるイベントでは startTime／endTime、終日イベントでは startDate／endDate が含まれます。また、設定されている場合は description、location、rrule、recurrenceId、status、url、categories、priority、organizer、attendeeCount も含まれます。

create_event

update_event

渡したフィールドのみが変更されます。

delete_event

イベントの参照

get_events と create_event は、各イベントについて uid と不透明な handle の2つの識別子を返します。update_event と delete_event には handle を渡してください。handle はそれだけで完結しており、新しいプロセスからでも使用できるため、通常は get_events（または create_event）でハンドルを取得し、それを使って update_event／delete_event を実行します。セッションをまたぐ追加の検索手順は不要です。

uid のみを渡すこともできますが、同じセッション内で以前に取得したイベントに限られ、短期間のインメモリキャッシュを通じて解決されます。UID によるステートレスなサーバー側検索には対応していません。iCloud は CalDAV の calendar-query UID prop-filter を拒否し（HTTP 412）、フィルターを指定しないクエリではカレンダー全体が返されるためです。handle の使用を推奨します。

ハンドルにはイベントの ETag が含まれています。ハンドルの発行後にイベントが別の場所で変更されていた場合、新しいバージョンを上書きせず、編集は競合として報告されます。新しいハンドルを取得するには get_events を再実行してから、もう一度試してください。成功すると、update_event は新しい ETag を含む更新済みのハンドルを返すため、編集を続ける場合は次の操作にそのハンドルを使用してください。

繰り返しイベントの編集

get_events は、繰り返しイベントの各回について、それぞれ固有の handle を持つ結果を1件ずつ返します。特定の回のハンドルを編集または削除する場合は、scope を設定してください。

• this_occurrence：その回のみ変更またはキャンセルします。
• this_and_future：その回と、それ以降のすべての回を変更します。
• all_events：シリーズ全体を変更します。

ハンドルがシリーズの特定の回を指している場合、scope の指定が必須です。指定しないと操作は拒否されるため、1回のみの編集で誤ってシリーズ全体が変更されることはありません。単独のイベントでは scope を省略してください。rrule、rdates、exdates は this_occurrence または this_and_future と併用できません。

アラーム

create_event と update_event では、alarms 配列を指定できます。各項目はオブジェクトです。

update_event で既存のアラームを維持するには alarms を省略し、削除するには空の配列を渡し、置き換えるにはリストを渡してください。

トラブルシューティング

新しいイベントがすぐに表示されません。 iCloud では即時に表示される保証がないため、作成直後のイベントは、次の get_events の結果にしばらく表示されない場合があります（CDN のインデックス作成の遅延）。create_event の成功レスポンスが確定情報です。イベントを再作成しないでください。

get_events でサイズまたは件数のエラーが返されます。 範囲が広すぎます。1週間または1か月ずつクエリしてください。レスポンスの上限は1000件です。

認証に失敗します。 Apple ID のパスワードではなくアプリ用パスワードを使用し、ICLOUD_USERNAME には iCloud のメールアドレス全体を設定してください。

どの calendar_id を使えばよいかわかりません。 list_calendars を呼び出し、使用するカレンダーの id を指定してください。

繰り返しイベントの編集が拒否されたか、すべての回が変更されました。 scope を設定してください（繰り返しイベントの編集を参照）。特定の回のハンドルには this_occurrence、this_and_future、または all_events が必要です。

タイムゾーンによって時刻がずれて見えます。 get_events は UTC の日境界を使用します（get_eventsを参照）。時刻指定のイベントを作成する際は timezone を渡し、現地の日付を解決するには追加日を含める方法を使用してください。

セキュリティ

このサーバーは、OWASP MCP Top 10 のガイドラインに従い、セキュリティを最優先に設計されています。

プライバシー

サーバーが通信するのは、マシン（STDIO 経由）と iCloud（caldav.icloud.com）のみです。テレメトリーはなく、カレンダーデータがほかの場所に送信されることもありません。認証情報は環境変数から取得され、ログに記録されることはありません。

セキュリティ制御

OWASP MCP Top 10 の対応状況

セキュリティに関する詳細なドキュメントと脆弱性の開示手順については、SECURITY.md を参照してください。

テスト

テストは、MCP サーバーモジュールとベンダー提供の icaldav-core iCalendar ライブラリの 2 か所にあります。どちらも次のコマンドで実行できます。

./gradlew test

テストカバレッジ（MCP サーバー）

セキュリティテストのカテゴリ

特定のテストの実行

# All tests
./gradlew test

# Security tests only
./gradlew test --tests "*SecurityTest*"
./gradlew test --tests "AdversarialTest"

# OWASP MCP specific tests
./gradlew test --tests "OwaspMcpSecurityTest"

# Unicode security tests
./gradlew test --tests "UnicodeSecurityTest"

# ReDoS protection tests
./gradlew test --tests "ReDoSSecurityTest"

# CalDAV tests
./gradlew test --tests "*CalDav*"

# ICS tests
./gradlew test --tests "*Ics*"

アーキテクチャ

+------------------------------------------------------------------+
|                    MCP Server (STDIO Transport)                    |
|                                                                    |
|  +----------------+  +----------------+  +----------------------+  |
|  | Rate Limiter   |  |   Input        |  |  Secure Error        |  |
|  | 60r/20w/min    |  |  Validator     |  |  Handler             |  |
|  +----------------+  +----------------+  +----------------------+  |
|                                                                    |
|  +----------------+  +----------------+  +----------------------+  |
|  | MCP Logger     |  | Cancellation   |  |  Progress            |  |
|  | (RFC 5424)     |  | Manager        |  |  Reporter            |  |
|  +----------------+  +----------------+  +----------------------+  |
|                                                                    |
|  Tools: list_calendars | get_events | create_event |               |
|         update_event | delete_event                                |
|                                                                    |
|  Resources: calendar://calendars                                   |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                      CalendarService                               |
|  Orchestrates CalDAV operations, caches calendar metadata          |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                      CalDAV Client Layer                           |
|                                                                    |
|  +-------------------+  +-------------------+  +----------------+  |
|  | OkHttpCalDav      |  |  IcsParser        |  |  IcsBuilder    |  |
|  | Client            |  |  (icaldav-core)   |  |  (icaldav-core)|  |
|  +-------------------+  +-------------------+  +----------------+  |
|                                                                    |
|  +-------------------+  +-------------------+  +----------------+  |
|  | ICloudXml         |  |  IcsPatcher       |  |  EtagUtils     |  |
|  | Parser            |  |  (event edits)    |  |  (RFC 7232)    |  |
|  +-------------------+  +-------------------+  +----------------+  |
|                                                                    |
|  +-------------------+                                             |
|  | Credential        |                                             |
|  | Manager           |                                             |
|  +-------------------+                                             |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    iCloud CalDAV API                               |
|                    caldav.icloud.com                               |
+------------------------------------------------------------------+

開発

ビルド

# Build
./gradlew build

# Build fat JAR
./gradlew fatJar

# Run tests
./gradlew test

# Clean build
./gradlew clean build

プロジェクト構成

src/main/kotlin/org/onekash/mcp/calendar/
├── Main.kt                 # MCP server entry point
├── caldav/                 # CalDAV protocol implementation
│   ├── CalDavClient.kt     # Client interface
│   ├── CalDavModels.kt     # Domain models
│   ├── OkHttpCalDavClient.kt
│   ├── ICloudXmlParser.kt
│   └── EtagUtils.kt        # RFC 7232 ETag normalization
├── ics/                    # ICS format handling (via icaldav-core)
│   ├── IcsParser.kt        # Parse iCalendar data
│   ├── IcsBuilder.kt       # Generate iCalendar data
│   └── IcsPatcher.kt       # Patch existing events (CRLF-safe)
├── service/                # Business logic
│   └── CalendarService.kt  # CalDAV orchestration + event cache
├── security/               # Security controls
│   └── CredentialManager.kt
├── validation/             # Input validation
│   └── InputValidator.kt
├── error/                  # Error handling
│   └── SecureErrorHandler.kt
├── ratelimit/              # Rate limiting
│   └── RateLimiter.kt
├── logging/                # MCP logging
│   └── McpLogger.kt
├── progress/               # Progress reporting
│   └── ProgressReporter.kt
└── cancellation/           # Operation cancellation
    └── CancellationManager.kt

MCP Inspector を使用したテスト

ICLOUD_USERNAME="[email protected]" \
ICLOUD_PASSWORD="test-app-password" \
npx @mcp-use/inspector java -jar build/libs/icloud-calendar-mcp-*-all.jar

貢献

皆さまからの貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

セキュリティ上の問題

セキュリティ脆弱性については、責任ある開示プロセスに関する SECURITY.md をご覧ください。セキュリティ脆弱性について、公開の Issue を作成しないでください。

ライセンス

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

謝辞

• Anthropic による Model Context Protocol
• Anthropic と JetBrains による MCP Kotlin SDK
• 低レベルの ICS 解析に使用している ical4j（同梱の icaldav-core ライブラリ経由）
• HTTP クライアントに使用している OkHttp
• セキュリティガイダンスに使用している OWASP MCP Top 10