CalDAV MCP Server

CalDAV MCP サーバー

CalDAV MCP Server は、iCloud Calendar のイベントを管理する Model Context Protocol サーバーです。1 つのイベントに複数の VALARM リマインダーをネイティブでサポートしています。

最初のリリースで公式にサポートし、手動で動作検証したプロバイダーは iCloud Calendar のみです。このサーバーは、stdio または Streamable HTTP をサポートするあらゆる MCP クライアントで動作します。

この独立したプロジェクトは、Apple Inc. とは提携関係になく、同社から認可、後援、承認を受けていません。Apple および iCloud は、それぞれの所有者の商標です。

クイックスタート

Apple の App 用パスワードを作成し、クライアントに応じた方法を選択してください。

Claude Desktop（ワンクリック、Node.js のインストール不要）： caldav-mcp.mcpb をダウンロードして Claude Desktop で開き、Apple Account のメールアドレスと App 用パスワードを入力します。Claude Desktop 拡張機能を参照してください。

その他の stdio クライアント： Node.js 22 以降をインストールし、Gemini CLI や Claude Code など、JSON で設定する MCP クライアントにこのサーバーを追加します。

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["--yes", "@lukegskw/caldav-mcp@latest"],
      "env": {
        "CALDAV_USERNAME": "[email protected]",
        "CALDAV_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

クライアントを再起動し、カレンダーツールが 6 つ表示されていることを確認してください。以下のクライアントごとのセットアップおよびDocker デプロイを参照してください。設定ファイルには App 用パスワードが含まれるため、非公開にしてください。

ナビゲーション

• 概要
• 機能
• MCP ツール
• 技術スタック
• インストール
• 設定
• MCP クライアントのセットアップ
• 検証
• 制限事項
• コントリビューション
• リリース

概要

このサーバーは、設定済みの 1 つのアカウントを CalDAV 経由で iCloud に接続します。アカウントのカレンダーを検出し、正規化された読み取り・書き込み操作を MCP 経由で公開します。

更新では、未知のプロパティ、Apple 拡張機能、VTIMEZONE、繰り返しの例外、パッチで省略されたアラームなどを含む、iCalendar リソース全体を保持します。書き込みでは、不透明なリソース識別子と ETag を使用し、CalDAV のファイル名がイベント UID と一致すると仮定しません。

カレンダーリソースはメモリー内で処理されます。このサーバーはテレメトリーもアプリケーションデータベースも使用せず、iCalendar の生データは明示的に要求された場合にのみ返します。

特徴

• 設定された iCloud アカウントで利用可能なカレンダーを検出します。
• 半開区間の時間範囲内のイベントを一覧表示し、繰り返し発生するイベントを展開します。
• 時刻指定イベント、終日イベント、繰り返しイベントを作成します。
• イベントごとに表示アラームをゼロ個、1 個、または複数個設定できます。
• Apple カレンダーの移動時間（X-APPLE-TRAVEL-DURATION）を読み書きします。
• 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"
}

Apple カレンダーの移動時間を 30 分に設定した時刻指定イベント：

{
  "calendar_id": "opaque-calendar-id",
  "summary": "Dentist",
  "start": {
    "date_time": "2026-10-05T10:00:00+02:00",
    "timezone": "Europe/Amsterdam"
  },
  "end": {
    "date_time": "2026-10-05T10:30:00+02:00",
    "timezone": "Europe/Amsterdam"
  },
  "travel_minutes": 30
}

travel_minutes は、イベント開始前の固定の移動時間を設定します。この例では、移動は 09:30 に始まり、予定は 10:00～10:30 のままです。サーバーが受け付けるのは、時刻指定イベントに対する 1～1,440 の整数の分数です。移動時間なしでイベントを作成する場合は、このフィールドを省略するか、null を指定します。ルートの計算や、イベントの開始時刻、終了時刻、アラームの変更は行いません。

所要時間は Apple の X-APPLE-TRAVEL-DURATION 拡張に保存されます。他のカレンダークライアントでの表示は、この拡張への対応状況によって異なります。返されるイベントには、最も近い整数の分に丸めた travel_minutes が含まれます。所要時間がない場合、無効な場合、または丸めた結果がゼロになる場合は null となります。

update_event

イベントまたは繰り返しシリーズのマスターイベントにパッチを適用します。省略されたフィールドは保持され、null を指定すると null 許容フィールドが削除され、alarms: [] を指定するとすべてのアラームが削除されます。任意の expected_etag を指定すると、サーバーのより新しいバージョンを上書きしないようにできます。

移動時間については、現在の値を維持する場合は patch.travel_minutes を省略し、所要時間を置き換える場合は数値を指定し、削除する場合は null を指定します。たとえば、"patch": { "travel_minutes": null } とすると、移動時間がクリアされます。移動時間が設定されたイベントを終日イベントに変換する場合は、新しい開始日と終了日に加えて travel_minutes: null を指定してください。既存の繰り返し例外には、それぞれの移動時間の設定が保持されます。

delete_event

イベントまたは繰り返しシリーズ全体を削除します。任意で、確認済みの ETag を必須にできます。現在のリリースでは、展開された単一の発生回のみを削除することはできません。

技術スタック

• Node.js 22+（Node.js の要件を参照）
• 厳格なプロジェクトルールを適用したTypeScript
• Model Context Protocol TypeScript SDK
• tsdav
• ical.js
• Zod
• Vitest
• pnpm
• Docker

インストール

前提条件

• カレンダーが有効になっているiCloudアカウント。
• Apple Accountで2ファクタ認証が有効になっていること。
• App用パスワード。
• コンテナでデプロイする場合はDockerとDocker Compose、npxを使う場合はNode.js 22+、ワンクリック拡張機能を使う場合はClaude Desktop。
• pnpmが必要なのはソースからビルドする場合のみです。CorepackとCIでは、package.jsonで固定されたバージョンを使用します。

Node.js の要件

用途	Node.js
Claude Desktop 拡張機能（.mcpb）	インストール不要。Claude Desktopに組み込みのNode.jsを使用します
npxまたはnpmのグローバルインストール	22 LTS以降。CIでは22と24をテストします
Dockerイメージ	インストール不要。イメージにはNode.js 24が含まれています
ソースからのビルドとコントリビューション	22.13以降が必要です（ESLint 10とVitest 5の要件）。24を推奨します

package.jsonのengines.nodeは>=22です。Node.js 20は2026年4月にサポート終了となり、サポート対象外です。古いバージョンではnpmがEBADENGINE警告を表示します。MCPクライアントが使用するバージョンは、node --versionで確認してください。デスクトップクライアントでは、ターミナルとは異なるnodeが使われる場合があります。クライアントがサーバーを起動できない場合は、Node.js 22+のnpxの絶対パスを指定してください（macOS/Linuxではcommand -v npx、Windowsではwhere npx）。

npm / npx

グローバルインストールやリポジトリのクローンは不要です。MCPクライアントから、公開済みの最新パッケージを直接起動できます。

CALDAV_USERNAME='[email protected]' \
CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx' \
npx --yes @lukegskw/caldav-mcp@latest

このコマンドはstdinでMCPメッセージを待ち受け、通常はstdoutに何も出力しません。実際には、MCPクライアントの設定に示すようにクライアント設定に追加してください。再現性のある環境で使う場合は、latestをX.Y.Zのような公開済みの特定バージョンに置き換えてください。

Docker Compose

推奨するインストール方法では、公開済みのマルチアーキテクチャイメージを使用します。

ghcr.io/lukegskw/caldav-mcp:latest

Composeのサンプルをダウンロードします。

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

Apple AccountのメールアドレスとApp用パスワードを設定してから、サービスを起動します。

export CALDAV_USERNAME='[email protected]'
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タグは最新の安定版リリースを指します。安定版リリースでは、0.1.6のような特定バージョンのタグと、0.1のようなマイナーシリーズのタグも公開されます。Composeのサンプルでは、デプロイの再現性を確保するため、ダイジェストでlatestを固定しています。アップグレードするには、更新されたComposeのサンプルをダウンロードするか、イメージ参照全体を使用する公開済みのバージョンとダイジェストに置き換えてください。

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 のローカルインストール

ソースからビルドするには Node.js 22.13 以降が必要です。Node.js 24 を推奨します。 ビルドと型チェックには TypeScript 7 を使用します。typescript 依存関係は、 ESLint が引き続き TypeScript 6 API を必要とするため、@typescript/typescript6 を エイリアスとして指定しています。@typescript/native は TypeScript 7 の tsc 実行ファイルを提供します。TypeScript の移行ガイダンスを参照してください。

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 モードでは、標準出力は 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 Account のメールアドレスです。
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 クライアントのセットアップ

Claude Desktop 拡張機能（推奨）

macOS および Windows 版の Claude Desktop では、ワンクリックでインストールできる MCP Bundle としてサーバーをインストールし、組み込みの Node.js で実行します。

1. 最新リリースから caldav-mcp.mcpb をダウンロードします。
2. Claude Desktop で開き（ダブルクリックするか、Settings -> Extensions にドラッグします）、Install を選択します。
3. Apple Account のメールアドレスとアプリ用パスワードを入力します。パスワードは機密設定として保存されます。

アップグレードするには、新しいリリースの .mcpb をインストールします。バンドルの内容とビルドおよびリリース方法については、 Claude Desktop extension を参照してください。

Gemini CLI 拡張機能

GitHub から直接インストールし、拡張機能の自動更新を有効にします。

gemini extensions install https://github.com/lukegskw/caldav-mcp --auto-update

Gemini はユーザー名の入力を求め、アプリ用パスワードを機密設定として保存します。公開拡張機能ギャラリーでは、このリポジトリのタグ付きリリースが検出されます。

手動設定

Streamable HTTP サーバー定義を受け付ける MCP クライアントでは、URL を設定します。

mcp_servers:
  caldav:
    url: http://<host>:8100/mcp

クライアントが Compose ネットワークを共有している場合は、サービス名と内部ポートを使用します。

mcp_servers:
  caldav:
    url: http://caldav-mcp:8100/mcp

ローカルの stdio サーバーを起動するクライアントでは、 クイックスタートの npm コマンドを使用してください。デスクトップクライアントが npx を見つけられない場合は、macOS/Linux では command -v npx、Windows では where npx で表示される絶対パスを使用します。

Claude Desktop

拡張機能を使うのが最も簡単です。代わりにサーバーを手動で設定するには、クイックスタートの JSON を claude_desktop_config.json の mcpServers に追加し、Claude Desktop を完全に再起動します。ファイルの場所を推測せず、Settings -> Developer -> Edit Config からファイルを開いてください。

Claude Code

Claude Code では、同じ stdio サーバーをユーザースコープに追加できます。

claude mcp add --transport stdio --scope user \
  --env [email protected] \
  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  icloud-calendar -- npx --yes @lukegskw/caldav-mcp@latest

このコマンドは、Claude の MCP 設定に値を追加します。シェルの履歴が共有される環境や、安全でない形で保持される環境では実行しないでください。

Codex

Codex では、共有の CLI および IDE 設定にサーバーを追加できます。

codex mcp add icloud-calendar \
  --env [email protected] \
  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  -- npx --yes @lukegskw/caldav-mcp@latest

codex mcp list を実行して確認してください。より細かく制御するには、~/.codex/config.toml またはプロジェクトスコープの .codex/config.toml にある公式の Codex MCP 設定を使用してください。

Gemini CLI

Gemini CLI MCP の設定に従い、ユーザースコープの ~/.gemini/settings.json またはプロジェクトの .gemini/settings.json にある mcpServers の下にサーバーを追加します。

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["--yes", "@lukegskw/caldav-mcp@latest"],
      "env": {
        "CALDAV_USERNAME": "[email protected]",
        "CALDAV_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

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 に渡した引数はホストのプロセス一覧で確認できますが、環境変数ファイルの内容は表示されません。このファイルには設定で説明されている変数を記述します。

[email protected]
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
pnpm test:package
pnpm test:distribution
pnpm build:mcpb
pnpm test:mcpb

最後に、MCP クライアントで接続し、6 つすべてのツールが一覧に表示されることを確認します。

制限事項

• サーバープロセスまたはコンテナごとに設定できる iCloud アカウントは 1 つです。
• 現在のリリースでは、Streamable HTTP エンドポイントに認証機能はありません。信頼できる LAN、VPN、またはプライベートなコンテナネットワーク内に制限し、インターネットに直接公開しないでください。
• 個々の繰り返し予定は読み取り専用です。シリーズ全体の更新または削除はサポートされています。
• 作成されるアラームは ACTION:DISPLAY のみです。
• 個々の iCalendar リソースの上限は 5 MiB です。
• イベント一覧の期間は 366 日まで、ページあたりの結果は 500 件までです。
• イベントに設定できるアラームは最大 20 件です。
• 参加者のスケジュール管理は現在の対象範囲外です。
• iCloud 以外のプロバイダーは公式にはサポートされていません。

セキュリティ上の問題を報告したり、診断情報を添付したりする前に、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 のルールを満たす必要があります。

リリース

リリースはバージョンに基づいており、main から自動化されます。これにより、レジストリの一部で障害が発生した場合でも、2 つ目の npm バージョンを公開することなく再試行できます。

1. pnpm release:prepare X.Y.Z で新しいバージョンを準備します。npm、MCP Registry、Gemini、MCP Bundle（manifest.json）のメタデータが同期されます。
2. pnpm test:distribution と pnpm test:mcpb を含む検証スイートを実行します。
3. リリース変更をコミットし、main にプッシュします。
4. リリースワークフローがコミットを検証し、公開前に対応する vX.Y.Z タグを自動的に作成します。

リリースワークフローではバージョンを検証し、パッケージ化された npm アーティファクトと Claude Desktop バンドルをテストしたうえで、正確なバージョン、マイナーシリーズ、latest のコンテナタグを、npm パッケージ、MCP Registry エントリー、caldav-mcp.mcpb を添付した GitHub リリースとともに公開します。プレリリースには正確なバージョンのコンテナタグのみが付与されます。Gemini は、リリースごとに別途編集しなくても、タグ付けされた拡張機能を検出できます。再実行時は、すでに存在する一致するアーティファクトをスキップし、不足している手順を再開します。.mcpb バンドルのビルド、テスト、公開については、Claude Desktop extension を参照してください。

ライセンス

MIT。LICENSE を参照してください。