icloud-calendar-mcp

信頼性が高く軽量な Apple iCloud Calendar MCP サーバーです。ネイティブ TypeScript/Node.js で、CalDAV 経由で iCloud に直接接続します。Java、Python、Go、AppleScript、macOS、Calendar.app には依存しません。

English summary: A production-oriented, cross-platform TypeScript MCP server for Apple iCloud Calendar. It provides guarded CalDAV CRUD, persistent opaque handles, idempotent writes, ETag concurrency control, recurrence expansion, stdio and secured Streamable HTTP transports.

インストール

Node.js 20 以降が必要です。Apple の「アプリケーション固有のパスワード」を使用する必要があります。Apple アカウントのマスターパスワードは使用しないでください。

npx icloud-calendar-mcp

アプリケーション固有のパスワードを作成する: account.apple.com にログインし、「ログインとセキュリティ」→「アプリケーション固有のパスワード」に進みます。Apple は同時にアクティブにできるアプリケーション固有のパスワードの数を制限する場合があります。パスワードを取り消すと、本サービスは AUTH_FAILED を受信します。

stdio クライアント設定:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["-y", "icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "you@example.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

stdout は JSON-RPC 専用です。すべてのログは stderr に書き込まれます。

Related MCP server: Chronos MCP

ツールと MCP コンテンツ

ツールは structuredContent とテキスト JSON の両方を返し、read-only/destructive/idempotent/open-world の注釈を宣言します。リソース: calendar://calendars。明示的なユーザーテンプレートプロンプト: schedule_event、reschedule_event、find_conflicts。これらはユーザーに代わって自主的にスケジュールを決定することはありません。

イベントは、時刻指定/終日、タイトル、説明、場所、URL、RRULE、DISPLAY アラーム、参加者をサポートします。参加者フィールドは iCloud とカレンダー共有の権限に制限されます。本サービスは「ATTENDEE への書き込み」を招待状の送信成功として誤って報告することはありません。

時刻と繰り返しイベントのセマンティクス

• 時刻指定イベントの入力には ISO 8601 時刻と IANA timezone を指定する必要があります。出力でもタイムゾーンが明示的に返されます。

• 終日イベントの start/end は YYYY-MM-DD を使用します。end はイベントに 含まれません。例: 8月18日の終日イベントは start=2026-08-18、end=2026-08-19 となります。

• iCalendar は ical.js を使用して構築および解析されます。ユーザーフィールドを文字列連結することはありません。テストでは DST、UTC、終日の境界をカバーします。

• list_events は CalDAV calendar-data/expand リクエストを通じて RRULE occurrence を展開します。

• whole_series は更新/削除をサポートします。single_occurrence、this_and_future は、iCloud の繰り返し例外機能が検証されていない場合、UNSUPPORTED_OPERATION を返し、決して静かにシリーズ全体に変更することはありません。

HTTP モード

HTTP はデフォルトでオフになっています。有効にすると loopback のみをリッスンし、bearer token は少なくとも 24 文字必要です:

ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx icloud-calendar-mcp

• MCP エンドポイント: POST /mcp

• ヘルスチェック: GET /healthz（Apple にアクセスせず、アカウントの状態も漏洩しません）

• bearer token を強制します。固定された Host allowlist。Origin はデフォルトですべて拒否。デフォルトのリクエスト上限は 1 MiB。ローカルの読み取り/書き込みレート制限。タイムアウトとセキュリティ応答ヘッダーの境界。

• ICLOUD_MCP_CONFIG=/absolute/path/config.json を使用して、allowedHosts、allowedOrigins、timeoutMs、maxEvents、読み取り/書き込みレート制限、リクエスト上限などの安定したパラメータを設定します。認証情報はこのファイルに入れることはできません。

完全な設定契約については docs/tool-contracts.md を、セキュリティモデルについては docs/security.md を参照してください。

信頼性

• create の UID は request_id の安定した SHA-256 派生値です。重複したリクエストによって2つ目のイベントが生成されることはありません。

• create は If-None-Match: * を使用し、update/delete は既に読み取った ETag の If-Match を使用します。

• ジャーナルはアトミックな rename でユーザーデータディレクトリ（デフォルトは ~/.icloud-caldav-mcp/journal.json、権限は厳格化）に書き込まれ、リクエストのリプレイと不透明なハンドルを保存します。

• 429/5xx/ネットワークの一時的な障害には、ジッター付きの指数バックオフを使用し、Retry-After を尊重します。応答に ETag がない場合は、read-after-write の可視性ポーリングを行います。

• 安定したエラーコード: AUTH_FAILED、CALENDAR_NOT_FOUND、EVENT_NOT_FOUND、ETAG_CONFLICT、INVALID_EVENT、RATE_LIMITED、TEMPORARY_UNAVAILABLE、UNSUPPORTED_OPERATION。

開発と実アカウントを用いた smoke test

pnpm install
pnpm check
pnpm pack

ユーザーに影響のある変更は pnpm changeset を使用して記録します。main にプッシュすると、Changesets が自動的に Release PR を作成または更新します。その PR がマージされると、npm Trusted Publishing を通じて自動的に公開され、provenance が付与されます。初めて有効にする前に、npm パッケージ設定で .github/workflows/release.yml を Trusted Publisher として設定する必要があります。

CI は fake adapter/HTTP fixtures を使用するため、実際の Apple アカウントは必要ありません。オプションの実際のテストは、ローカルで明示的に ICLOUD_USERNAME と ICLOUD_APP_PASSWORD を指定した場合にのみ実行されます: pnpm smoke:icloud。現在の smoke スイートはデフォルトで書き込み操作をスキップします。最初の実際の検証では、専用のテストカレンダーを使用して、discovery/list/create/update/delete/recurrence exception の動作を手動で検証することをお勧めします。

トラブルシューティング: 401/403 の場合はアプリケーション固有のパスワードを確認してください。412 は ETag の同時実行競合を示します。list_events/get_event を再実行してください。429 の場合は待機してから再試行してください。不明なハンドルは、ジャーナルが削除されたか、データディレクトリが変更されたことを示します。完全な CalDAV URL、Authorization、またはイベント本文を issue に貼り付けないでください。

ライセンス

MIT。独立したオリジナルコードとして実装されています。公開プロジェクトはインターフェースとアーキテクチャの差異調査のためだけに使用されており、サードパーティのソースコードはコピーされていません。