Skip to main content
Glama

CalDAV MCP Server

TypeScript CI Container License

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 を要求します。単一の展開された発生の削除は、現在のリリースではサポートされていません。

技術スタック

インストール

前提条件

  • カレンダーが有効な iCloud アカウント。

  • Apple アカウントで 2 要素認証が有効になっていること。

  • アプリ固有のパスワード。

  • コンテナ展開用の Docker と Docker Compose、またはローカルインストール用の Node.js 24+ と pnpm。

Docker Compose

推奨されるインストール方法は、公開されているマルチアーキテクチャイメージを使用します:

ghcr.io/lukegskw/caldav-mcp:latest

Compose の例をダウンロードします:

curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yaml

Apple アカウントのメールアドレスとアプリ固有のパスワードを指定し、サービスを開始します:

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 -d

latest タグは、デフォルトブランチからの最新の成功したビルドに追従します。管理された展開またはロールバックの場合は、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 stdio

stdio モードでは、stdout は MCP メッセージ専用に予約されています。Streamable HTTP をローカルで実行するには:

CALDAV_MCP_TRANSPORT=streamable-http pnpm start

設定

すべての設定は CALDAV_ または CALDAV_MCP_ プレフィックスを使用します。

変数

必須

デフォルト

説明

CALDAV_PROVIDER

いいえ

icloud

プロバイダーポリシー。iCloud がサポートされるプロファイルです。

CALDAV_URL

いいえ

https://caldav.icloud.com

CalDAV 検出 URL。

CALDAV_USERNAME

はい

なし

Apple アカウントのメールアドレス。

CALDAV_PASSWORD

はい

なし

アプリ固有のパスワード。アカウントのパスワードではありません。

CALDAV_MCP_TRANSPORT

いいえ

stdio

stdio または streamable-http。

CALDAV_MCP_HOST

いいえ

0.0.0.0

HTTP バインドアドレス。

CALDAV_MCP_PORT

いいえ

8100

HTTP リッスンポート。

CALDAV_MCP_LOG_LEVEL

いいえ

INFO

アプリケーションログレベル。

CALDAV_MCP_REQUEST_TIMEOUT_MS

いいえ

30000

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-xxxx

latest の代わりにダイジェストでイメージを固定すると、クライアントの再起動時に異なるバージョンが静かに起動するのを防げます:

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 tools
create_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 eventA
DestructiveIdempotent

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 eventA
Read-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 calendarsA
Read-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 eventsA
Read-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 eventA
Destructive

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

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: create_event, list_events, get_event, update_event, delete_event, list_calendars.

    Tool Count5/5

    Six tools are well-scoped for a CalDAV server: one discovery tool and a complete event CRUD set. No tool appears redundant or trivial.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers