CalDAV MCP Server
CalDAV MCP Server
CalDAV MCP Server は、iCloud カレンダーのイベントを管理するための Model Context Protocol サーバーです。1 つのイベントに複数の VALARM リマインダーをネイティブに設定できます。
iCloud カレンダーは、最初のリリースで公式にサポートされ、手動検証が行われた唯一のプロバイダーです。このサーバーは、stdio または Streamable HTTP をサポートする任意の MCP クライアントで動作します。
この独立したプロジェクトは、Apple Inc. とは提携、承認、後援、または承認を受けておらず、Apple および iCloud はそれぞれの所有者の商標です。
ナビゲーション
Related MCP server: DAV MCP Server
概要
このサーバーは、設定された 1 つのアカウントを CalDAV 経由で iCloud に接続します。アカウントのカレンダーを検出し、正規化された読み取りおよび書き込み操作を MCP を通じて公開します。
更新時には、未知のプロパティ、Apple 拡張、VTIMEZONE、繰り返し例外、パッチで省略されたアラームなど、完全な iCalendar リソースが保持されます。書き込みでは、CalDAV のファイル名がイベント UID と一致することを前提とせず、不透明なリソース識別子と ETag を使用します。
カレンダーリソースはメモリ内で処理されます。このサーバーにはテレメトリもアプリケーションデータベースもなく、生の iCalendar は明示的に要求された場合にのみ返されます。
機能
設定された iCloud アカウントで利用可能なカレンダーを検出します。
半開区間の時間範囲でイベントを一覧表示し、繰り返しの発生を展開します。
時刻指定、終日、繰り返しイベントを作成します。
イベントごとに 0 個、1 個、または複数の表示アラームをサポートします。
iCloud カレンダーが期待する Apple アラーム拡張を出力します。
不透明なリソース ID、またはカレンダー ID と UID のペアでイベントを読み取ります。
省略されたデータや未知の iCalendar データを保持しながら部分更新を適用します。
更新と削除の際に楽観的並行性制御のために ETag を使用します。
完全な繰り返しシリーズを変更する代わりに、単一の繰り返し変更を拒否します。
ログとエラーから資格情報、生のカレンダーコンテンツ、CalDAV パスを編集します。
読み取り専用のルートファイルシステム構成を持つ非 root コンテナとして実行されます。
stdioおよび Streamable HTTP MCP トランスポートをサポートします。
MCP ツール
list_calendars
設定されたアカウントで検出されたカレンダーを一覧表示します。各結果には、不透明な calendar_id、表示名、説明、タイムゾーン、およびベストエフォートの書き込みステータスが含まれます。
list_events
半開区間のイベントを一覧表示し、繰り返しの発生を展開します。最大範囲は 366 日、デフォルトのページサイズは 100、最大ページサイズは 500 です。結果は決定的な時系列順で返されます。ページネーションカーソルは不透明であり、走査中にイベントが変更された場合にスナップショットを表すものではありません。
入力例:
{
"calendar_id": "opaque-calendar-id",
"start": "2026-09-01T00:00:00Z",
"end": "2026-10-01T00:00:00Z",
"timezone": "Europe/Berlin",
"limit": 100
}get_event
resource_id、または calendar_id と UID のペアでイベントを読み取ります。生の iCalendar はデフォルトで除外され、制御された診断のために include_raw_ical: true で要求できます。
create_event
イベントを作成し、サーバーが保存した表現を読み戻します。
2 つのアラームを持つ時刻指定イベント:
{
"calendar_id": "opaque-calendar-id",
"summary": "Buy Shinkansen tickets",
"start": {
"date_time": "2026-09-06T03:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-06T03:30:00+02:00",
"timezone": "Europe/Berlin"
},
"description": "Smart-EX",
"location": null,
"alarms": [
{ "minutes_before": 1440, "action": "DISPLAY" },
{ "minutes_before": 0, "action": "DISPLAY" }
],
"rrule": null
}排他的な終了日を持つ終日イベント:
{
"calendar_id": "opaque-calendar-id",
"summary": "Trip",
"start": { "date": "2026-09-06" },
"end": { "date": "2026-09-08" },
"alarms": []
}繰り返しイベントは、RRULE: プレフィックスなしの RFC 5545 ルールを受け入れます:
{
"calendar_id": "opaque-calendar-id",
"summary": "Weekly planning",
"start": {
"date_time": "2026-09-07T09:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-07T09:30:00+02:00",
"timezone": "Europe/Berlin"
},
"rrule": "FREQ=WEEKLY;BYDAY=MO;COUNT=10"
}update_event
イベントまたは完全な繰り返しシリーズをパッチします。省略されたフィールドは保持され、null は null 許容フィールドを削除し、alarms: [] はすべてのアラームを削除します。オプションの expected_etag は、より新しいサーバーバージョンの上書きを防ぎます。
delete_event
イベントまたは完全な繰り返しシリーズを削除し、オプションで観測された ETag を要求します。単一の展開された発生の削除は、現在のリリースではサポートされていません。
技術スタック
厳格なプロジェクトルールを持つ TypeScript
インストール
前提条件
カレンダーが有効な iCloud アカウント。
Apple アカウントで 2 要素認証が有効になっていること。
コンテナ展開用の Docker と Docker Compose、またはローカルインストール用の Node.js 24+ と pnpm。
Docker Compose
推奨されるインストール方法は、公開されているマルチアーキテクチャイメージを使用します:
ghcr.io/lukegskw/caldav-mcp:latestCompose の例をダウンロードします:
curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yamlApple アカウントのメールアドレスとアプリ固有のパスワードを指定し、サービスを開始します:
export CALDAV_USERNAME='user@example.com'
export CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx'
docker compose -f compose.example.yaml up -d異なるホストポートを公開するには、次を設定します:
export CALDAV_MCP_PUBLISHED_PORT=18100
docker compose -f compose.example.yaml up -dlatest タグは、デフォルトブランチからの最新の成功したビルドに追従します。管理された展開またはロールバックの場合は、Compose ファイル内のタグを公開されたバージョンまたは不変の sha-* タグに置き換えます。
Streamable HTTP エンドポイントは、次の場所で利用可能になります:
http://<host>:8100/mcpホストポートは、コンテナ内のポート 8100 を変更せずに変更できます。永続ボリュームは不要です。カレンダーデータは iCloud に残ります。
Docker run
同じ強化されたコンテナ構成を直接開始できます:
docker run -d \
--name caldav-mcp \
--restart unless-stopped \
--read-only \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:size=16m,mode=1777 \
-e CALDAV_PROVIDER=icloud \
-e CALDAV_USERNAME \
-e CALDAV_PASSWORD \
-e CALDAV_MCP_TRANSPORT=streamable-http \
-e CALDAV_MCP_HOST=0.0.0.0 \
-p 8100:8100 \
ghcr.io/lukegskw/caldav-mcp:latestソースからコンテナをビルドする
ローカルでのビルドはオプションです。コンテナビルドを変更または監査する必要がない限り、公開されたイメージを優先してください。
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
docker buildx build --load -t caldav-mcp:local .ローカル Node.js インストール
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
pnpm install --frozen-lockfile
cp .env.example .env
pnpm build
pnpm start -- --transport stdiostdio モードでは、stdout は MCP メッセージ専用に予約されています。Streamable HTTP をローカルで実行するには:
CALDAV_MCP_TRANSPORT=streamable-http pnpm start設定
すべての設定は CALDAV_ または CALDAV_MCP_ プレフィックスを使用します。
変数 | 必須 | デフォルト | 説明 |
| いいえ |
| プロバイダーポリシー。iCloud がサポートされるプロファイルです。 |
| いいえ |
| CalDAV 検出 URL。 |
| はい | なし | Apple アカウントのメールアドレス。 |
| はい | なし | アプリ固有のパスワード。アカウントのパスワードではありません。 |
| いいえ |
|
|
| いいえ |
| HTTP バインドアドレス。 |
| いいえ |
| HTTP リッスンポート。 |
| いいえ |
| アプリケーションログレベル。 |
| いいえ |
| CalDAV リクエストタイムアウト。 |
コアは、Apple 拡張を共有の iCalendar 実装から分離するために、実験的な generic プロバイダーポリシーと設定可能な URL を保持しています。現在、他のプロバイダーとの互換性は主張されていません。
シークレットは、デプロイメントプラットフォームまたは環境を通じて提供する必要があります。.env をコミットしたり、資格情報を MCP ツールの引数として渡したり、診断レポートに含めたりしないでください。
MCP クライアントのセットアップ
Streamable HTTP サーバー定義を受け入れる任意の MCP クライアントで、URL を設定します:
mcp_servers:
caldav:
url: http://<host>:8100/mcpクライアントが Compose ネットワークを共有している場合は、サービス名と内部ポートを使用します:
mcp_servers:
caldav:
url: http://caldav-mcp:8100/mcpローカルの stdio サーバーを起動するクライアントの場合は、必要な環境変数を使用して node /absolute/path/to/caldav-mcp/dist/main.js を実行するようにコマンドを設定します。
Claude Desktop (Docker、stdio)
Claude Desktop は、ローカルの stdio サーバーをサブプロセスとして起動します。公開されたコンテナをこの方法で実行すると、アプリ固有のパスワードがクライアントマシンに保持され、ネットワークポートが開かれず、制限事項 のトランスポートガイダンスに一致します。
claude_desktop_config.json にサーバーを追加します:
{
"mcpServers": {
"icloud-calendar": {
"command": "/absolute/path/to/docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/absolute/path/to/caldav-mcp.env",
"-e",
"CALDAV_PROVIDER=icloud",
"-e",
"CALDAV_MCP_TRANSPORT=stdio",
"ghcr.io/lukegskw/caldav-mcp@sha256:<digest>"
]
}
}
}-i は必須です。アタッチされた stdin がないと、クライアントはコンテナと MCP 通信できません。--rm は、クライアントがコンテナを停止するとコンテナを削除します。
資格情報は -e ではなく --env-file で指定します。docker run に渡された引数はホストのプロセスリストに表示されますが、env ファイルの内容は表示されません。ファイルには 設定 で説明されている変数が含まれます:
CALDAV_USERNAME=user@example.com
CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxxlatest の代わりにダイジェストでイメージを固定すると、クライアントの再起動時に異なるバージョンが静かに起動するのを防げます:
docker pull ghcr.io/lukegskw/caldav-mcp:latest
docker images --digests ghcr.io/lukegskw/caldav-mcp設定ファイルを編集した後、Claude Desktop を完全に再起動します。
Windows
設定 -> 開発者 -> 設定の編集 から設定ファイルを作成して配置します。パスを推測しないでください。Claude Desktop が Microsoft Store からインストールされている場合、Windows は %APPDATA%\Claude をパッケージコンテナにリダイレクトし、ファイルは次の場所にあります:
%LOCALAPPDATA%\Packages\Claude_<package-id>\LocalCache\Roaming\Claude\claude_desktop_config.jsonその場合、dir %APPDATA%\Claude は何も報告しません。サーバーログは設定ファイルの隣の logs\mcp-server-<server-name>.log に書き込まれます。
パッケージコンテナ内の PATH は信頼できないため、docker.exe への絶対パスを使用します。where docker でパスが表示されます。通常は C:\Program Files\Docker\Docker\resources\bin\docker.exe です。JSON ではバックスラッシュをエスケープする必要があります。
設定形式は MCP クライアントによって異なります。クライアントのドキュメントで正確なスキーマを確認し、サーバー定義を変更した後はリロードまたは再起動してください。
検証
コンテナの状態とログを確認します:
docker compose -f compose.example.yaml ps
docker compose -f compose.example.yaml logs caldav-mcpコンテナは healthy を報告するはずです。TCP ヘルスチェックはサーバープロセスを検証し、iCloud の資格情報は検証しません。
リポジトリの検証スイートを実行します:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build最後に、MCP クライアントで接続し、6 つのツールすべてが一覧表示されることを確認します。リリース前に、専用の iCloud 手動検証 をテストカレンダーに対して実行します。
制限事項
サーバープロセスまたはコンテナごとに 1 つの iCloud アカウントが設定されます。
Streamable HTTP エンドポイントには、現在のリリースでは認証がありません。信頼できる LAN、VPN、またはプライベートコンテナネットワークに制限し、インターネットに直接公開しないでください。
個々の繰り返しの発生は読み取り専用です。完全なシリーズの更新または削除はサポートされています。
ACTION:DISPLAYアラームのみが作成されます。個々の iCalendar リソースは 5 MiB に制限されています。
イベント一覧の範囲は 366 日、ページは 500 件に制限されています。
イベントには最大 20 個のアラームを含めることができます。
参加者のスケジューリングは現在の範囲外です。
iCloud 以外のプロバイダーは公式にはサポートされていません。
検出、認証、ETag、および Apple 拡張のガイダンスについては、トラブルシューティング を参照してください。セキュリティの問題を報告したり、診断情報を添付したりする前に、SECURITY.md を確認してください。
コントリビューション
コントリビューションを歓迎します。プルリクエストを開く前に:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t caldav-mcp:test .CalDAV 書き込みまたは iCalendar シリアライゼーションへの変更は、ETag チェック、不透明なリソース境界、未知のプロパティ、繰り返し例外、パッチで省略されたアラームを保持する必要があります。TypeScript の変更は、.codex/rules/typescript.md のルールを引き続き満たす必要があります。
ライセンス
MIT。 LICENSE を参照してください。
Available Tools
6 toolscreate_eventCreate calendar eventA
Create a new event in a writable iCloud calendar and return the stored representation; existing events are not changed. Use list_calendars first to obtain calendar_id, and use update_event when the event already exists. Timed values require matching offsets and timezones, all-day end dates are exclusive, recurrence rules omit the RRULE: prefix, and travel_minutes sets Apple Calendar travel time for timed events.
Inputs: end (required), start (required), summary (required), calendar_id (required), +5 more. Returns: end, uid, etag, href, +13 more
delete_eventDelete calendar eventADestructiveIdempotent
Permanently delete an event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid, and supply expected_etag when available to prevent deleting a concurrently changed event.
Inputs: uid, calendar_id, resource_id, expected_etag. Returns: deleted, resource_id
get_eventGet calendar eventARead-onlyIdempotent
Read one event by resource_id, preferably from a previous result, or by the calendar_id and uid pair. Use list_events for range searches. Request raw iCalendar only for controlled diagnostics because it may contain sensitive calendar data.
Inputs: uid, calendar_id, resource_id, include_raw_ical. Returns: end, uid, etag, href, +13 more
list_calendarsList calendarsARead-onlyIdempotent
List calendars available in the configured iCloud account. Use this first to obtain the opaque calendar_id required by list_events and create_event; writable is a best-effort capability indicator.
Inputs: no named parameters. Returns: calendars
list_eventsList calendar eventsARead-onlyIdempotent
List events that overlap the start-inclusive, end-exclusive interval and expand recurring series into occurrences, across at most 366 days. Use list_calendars first to obtain calendar_id and use get_event instead for one known event. Continue with next_cursor and unchanged query filters when more results are available.
Inputs: end (required), start (required), calendar_id (required), limit, +2 more. Returns: events, next_cursor
update_eventUpdate calendar eventADestructive
Modify an existing event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid. Omitted patch fields are preserved, null clears nullable fields, an empty alarms array removes alarms, and expected_etag can prevent a stale write.
Inputs: patch (required), uid, calendar_id, resource_id, +1 more. Returns: end, uid, etag, href, +13 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct action on a distinct resource: create/list/get/update/delete events plus list calendars. The descriptions explicitly clarify boundaries, such as list_events vs get_event and update vs create.
All tool names follow a consistent verb_noun snake_case pattern: create_event, list_events, get_event, update_event, delete_event, list_calendars.
Six tools are well-scoped for a CalDAV server: one discovery tool and a complete event CRUD set. No tool appears redundant or trivial.
The surface covers full event lifecycle plus calendar discovery, which is the core domain. Minor gaps exist around calendar-level operations and individual recurring-occurrence edits, though these are documented limitations rather than dead ends.
Maintenance
Related MCP Connectors
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Model Context Protocol server for todo.vu task management and time tracking.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server for AI models to access and manipulate Apple Calendar data on macOS through a standardized interface.714MIT
- AlicenseDqualityDmaintenanceA Model Context Protocol server that allows users to interact with their CalDAV, CardDAV, and WebDAV services (calendars, contacts, and files) from Fastmail and Apple iCloud accounts.63MIT
- AlicenseNot gradedqualityCmaintenanceAn HTTP Model Context Protocol (MCP) server exposing iCloud Calendar (CalDAV) tools so MCP-aware clients can list calendars, read events, and create/update/delete events using an iCloud app-specific password.3MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar via native EventKit API with proper recurring event support.13 npm10MIT