iCloud Calendar (CalDAV)

iCloud Calendar MCP サーバー

MCP（Model Context Protocol） サーバーです。CalDAV 経由で MCP クライアントから iCloud Calendar にアクセスでき、カレンダーの一覧表示、イベントの読み取り、作成、更新、移動、削除ができます。macOS Calendar アプリを経由せず iCloud に直接接続するため、Linux、macOS、Windows で動作します。

zwrong/iCalendar を基にした、継続的にメンテナンスされているフォークです。zwrong/iCalendar 自体は macOS 向けの mcp-ical サーバーから派生しています。このフォークでの変更点をご覧ください。

ツール

ツール	説明
list_calendars	利用可能なカレンダーの名前
list_events	指定した期間内のイベント。必要に応じてカレンダーを指定でき、開始時刻順に並びます
create_event	新しいイベント：タイトル、時刻、終日、場所、メモ、URL、アラーム、繰り返し
update_event	これらのフィールドの変更、またはイベントの別カレンダーへの移動
delete_event	識別子を指定してイベントを削除
debug_calendar_connection	接続確認：過去 7 日間のカレンダーとイベント数

calendars://list リソースでもカレンダーを一覧表示できます。MCP_ICAL_READ_ONLY=true の場合、3 つの書き込みツールは登録されません。

要件

• Python 3.12 以降と uv
• iCloud Calendar が有効な Apple ID
• その Apple ID のApp 用パスワード

App 用パスワード

1. appleid.apple.com にサインインし、サインインとセキュリティ、次にApp 用パスワードを開きます。
2. パスワードを生成します。たとえば、mcp-icloud-caldav という名前を付けます。

ユーザー名は Apple ID のメールアドレスです。必ずしも @icloud.com のアドレスとは限りません。 App 用パスワードを使うと、iCloud CalDAV、CardDAV、IMAP にアクセスできます。バージョン管理に含めないでください。漏えいした場合は無効にしてください。

インストール

パッケージは PyPI に mcp-icloud-caldav として公開されています。uv を使うと、MCP クライアントから別途インストールせずに直接起動できます。

uvx mcp-icloud-caldav

初回の使用時に uvx がパッケージをキャッシュ済みの隔離環境にダウンロードします。代わりに恒久的にインストールするには、uv tool install mcp-icloud-caldav（または pipx install mcp-icloud-caldav）を実行します。

ソースからインストールする場合：

git clone https://github.com/Glob0x17/mcp-icloud-caldav.git mcp-icloud-caldav
cd mcp-icloud-caldav
uv sync --no-dev
uv run mcp-icloud-caldav

設定

認証情報は次の順序で読み込まれます。

1. 環境変数（推奨）

   変数	必須	デフォルト
   ICLOUD_USERNAME	はい
   ICLOUD_PASSWORD	はい
   CALDAV_SERVER_URL	いいえ	https://caldav.icloud.com/

2. MCP_ICAL_CONFIG：config.json.example と同じ形式の JSON ファイルへのパス

3. リポジトリのルートにある config_private.json、次に config.json（互換性のために維持されています）

その他の設定：

変数	デフォルト	効果
MCP_ICAL_READ_ONLY	false	true の場合、create_event、update_event、delete_event を除外します
MCP_ICAL_LOG_LEVEL	INFO	TRACE、DEBUG、INFO、WARNING、ERROR のいずれかです。ログは stderr に出力されます

サーバーは stdio 経由で MCP を通信し、クライアントによって起動されます。手動で確認するには：

[email protected] ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx uvx mcp-icloud-caldav

stdin で入力を待ち受け、stdout には何も出力しません。

クライアントの設定

クライアントが uvx を見つけられない場合は、uvx の絶対パス（which uvx）を使用してください。クライアントはシェルの PATH を使わずにサーバーを起動することが多く、その場合は spawn uvx ENOENT が表示されます。一般的な場所は次のとおりです。

インストール方法	パス
uv インストーラー（Linux、macOS）	~/.local/bin/uvx
Apple シリコン搭載 Mac の Homebrew	/opt/homebrew/bin/uvx
Intel Mac の Homebrew	/usr/local/bin/uvx

コマンドとその引数は別々のフィールドです。コマンドは uvx（またはそのパス）で、mcp-icloud-caldav は引数です。コマンドを単一の文字列 "uvx mcp-icloud-caldav" とする設定は、クライアントがスペースも含めたその名前のプログラムを探すため、ENOENT で失敗します。

クライアント設定にパスワードを記載しない方法

ほとんどのクライアントは、設定ファイルに env の値を平文で保存します。環境変数ファイルを読み込む小さなラッパーを使えば、それを避けられます。

mkdir -p ~/.config/mcp-icloud-caldav && chmod 700 ~/.config/mcp-icloud-caldav
cat > ~/.config/mcp-icloud-caldav/env <<'EOF'
[email protected]
ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx
MCP_ICAL_READ_ONLY=true
EOF
chmod 600 ~/.config/mcp-icloud-caldav/env

cat > ~/.local/bin/mcp-icloud-caldav-run <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
set -a; source "$HOME/.config/mcp-icloud-caldav/env"; set +a
exec /absolute/path/to/uvx mcp-icloud-caldav
EOF
chmod +x ~/.local/bin/mcp-icloud-caldav-run

その後、クライアントの接続先を ~/.local/bin/mcp-icloud-caldav-run に設定します。まず読み取り専用で開始し、読み取りが機能したら false に切り替えるのがよいでしょう。

Claude Desktop

claude_desktop_config.json（Settings、Developer、Edit Config）に設定します。macOS では次の場所にあります。 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["mcp-icloud-caldav"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

または、ラッパーを使う場合は "command": "/home/you/.local/bin/mcp-icloud-caldav-run" とし、env は設定しません。編集後は Claude Desktop を完全に終了してから再起動してください。macOS では、サーバーログは ~/Library/Logs/Claude/mcp-server-icloud-calendar.log にあります。

Claude Code

claude mcp add --scope user icloud-calendar \
  -e [email protected] -e ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  -- uvx mcp-icloud-caldav

または、ラッパーを使う場合は claude mcp add --scope user icloud-calendar -- ~/.local/bin/mcp-icloud-caldav-run を実行します。

-- の後に続く内容を引用符で囲まないでください。-- uvx mcp-icloud-caldav は、コマンドを uvx、引数を mcp-icloud-caldav として登録します。一方、-- "uvx mcp-icloud-caldav" は単一のプログラム名として登録するため、ENOENT で失敗します。既存のエントリーを修正するには、claude mcp remove icloud-calendar --scope user で削除してから、もう一度追加してください。

セッション内で /mcp を実行すると、サーバーの状態とツールが表示されます。claude mcp get icloud-calendar を実行すると、登録済みのコマンドと引数が表示されます。

その他のクライアント

stdio サーバーを起動できる MCP クライアントならどれでも動作します。上記の環境変数を設定したうえで、uvx mcp-icloud-caldav を実行してください。このサーバーは MCP Registry にも io.github.Glob0x17/mcp-icloud-caldav として掲載されています。

知っておくとよい動作

• 時刻。 イベントの時刻は UTC で書き込まれます。オフセット付きの時刻（2030-01-07T09:30:00+01:00）は変換され、オフセットのない時刻はマシンのローカル時刻として扱われます。時刻はマシンのタイムゾーンに変換して表示されます。終日イベントは日付として書き込まれ、iCalendar 標準の要件に従い、終了日は含まれません。
• カレンダー間の移動。 iCloud は同じイベント UID が 2 つのカレンダーに存在することを許可しないため、「コピーしてから削除」する方法では移動できません。calendar_name を指定した update_event は WebDAV の MOVE を使用するため、サーバー上でアトミックに処理されます。失敗した場合、イベントは元の場所に残ります。他の変更を加えずに移動すると、元の iCalendar データはそのまま維持されます。
• イベントの検索。 一覧表示によって、サーバープロセスが存続する間メモリ内に保持されるインデックス（UID から URL への対応）が作成されます。その後の検索ではイベントに直接アクセスし、見つからない場合は iCloud がほとんどのイベントに使用する <calendar>/<UID>.ics の URL を試し、それでも見つからない場合にのみすべてのカレンダーを走査します。iCloud は CalDAV の UID 検索をサポートしていません。
• 件数。 iCloud は 1 回のリクエストで任意の件数のイベントを返します。実質的な上限はクライアント側にあり、多くのクライアントはツールの結果を約 25,000 トークン（このサーバーの出力で約 300 件のイベント）に制限するため、長期間の範囲は分割してください。
• 対象範囲。 iCloud 上でホストされているカレンダーのみが表示されます。デバイスのカレンダーアプリに追加された Exchange、Google、その他のアカウントには、iCloud CalDAV 経由ではアクセスできません。また、読み取り専用で購読した（ICS）カレンダーにもアクセスできません。

プライバシーとセキュリティ

• ネットワーク接続先は設定された CalDAV サーバーのみで、テレメトリはありません。
• パスワードがログに出力されることは、どのログレベルでもなく、設定オブジェクトの repr に表示されることもありません。
• MCP プロトコルで stdout を使用するため、ログは stderr のみに出力されます。イベントの内容（タイトル、メモ）は DEBUG 以下でのみ記録され、INFO では識別子のみが記録されます。一部のクライアントはサーバーの stderr をディスクに保存するため、トラブルシューティングでは DEBUG を使用してください。
• 依存関係は uv.lock で固定され、公式 PyPI インデックスのみから解決されます。

トラブルシューティング

症状	考えられる原因
401 Unauthorized	アプリ用パスワードではなく通常の Apple ID パスワードを使用している、またはアプリ用パスワードが取り消されている
spawn uvx ENOENT または ENOENT	uvx がクライアントの PATH にない（絶対パスを使用してください）、またはコマンドとその引数が一つの文字列として登録されている（クライアントのセットアップを参照）
イベントが返されない	日付範囲が誤っている、iCloud 以外のカレンダーまたは購読中のカレンダーのイベントである、あるいはタイムゾーンが一致していない
サーバーが応答しない	何かが stdout に書き込み、stdio プロトコルを破損させている
Calendar 'X' not found	カレンダー名では大文字と小文字が区別されます。list_calendars を確認してください

debug_calendar_connection と MCP_ICAL_LOG_LEVEL=DEBUG を使うと、問題の原因を絞り込めます。

開発

uv sync
uv run pytest -m "not integration"   # unit tests, CalDAV client mocked, no network
uv run ruff check .

統合テストは実際のアカウントに対して読み取り専用で実行され、認証情報が設定されていない場合はスキップされます。

ICLOUD_USERNAME=... ICLOUD_PASSWORD=... uv run pytest -m integration

プロジェクトの構成：

mcp_icloud_caldav/
├── server.py          # MCP server, tool registration, logging setup
├── caldav_client.py   # CalDAV access: search, create, update, move, delete, event index
├── ical.py            # Thin calendar manager used by the server
├── models.py          # Event and request models, iCalendar parsing
└── config.py          # Configuration loading
tests/                 # Unit tests
tests/integration/     # Read-only tests against a real account

このフォークでの変更点

0.2.1：ドキュメントのみ（uvx の場所、ENOENT の原因、macOS でのクライアントのパス）。

0.2.0、zwrong/iCalendar 0.1.0 との比較：

• 依存関係。 ロックファイルを公式 PyPI インデックスから再生成しました（以前は HTTP 経由でサードパーティのミラーからパッケージを解決していました）。mcp 2.x（FastMCP が MCPServer に変更）および caldav 3.x にアップグレードしました。元のコードは、現在のリリースでは起動しなくなっています。
• 設定。 環境変数、MCP_ICAL_CONFIG、読み取り専用モード、設定可能なログレベルを追加し、DEBUG を超えるログレベルではイベントの内容を記録しないようにしました。
• 修正。
  • タイムゾーンオフセットを指定してイベントを作成すると失敗していました（Unable to guess TZID）。終日イベントと繰り返しイベントの終了日が誤って書き込まれていました。
  • アラームが読み戻されていませんでした。
  • 場所、メモ、URL のないイベントを更新すると失敗していました。イベントの時刻を変更すると、無効な iCalendar データが生成されていました。
  • イベントの移動時、コピーを保存する前に元のイベントを削除していたため、保存に失敗するとイベントが失われていました。
  • 新しいイベントの UID に空白とマシンのホスト名が含まれていました。
• 動作。 イベントを開始時刻順に並べ替え、空のフィールドを省いた簡潔な出力を行い、イベントインデックスをメモリ上に保持します。
• テスト。 設定、読み取り専用モード、ログ記録、iCalendar 出力、イベントの移動と検索を対象とするユニットテスト。
• パッケージング。 mcp-icloud-caldav として PyPI に公開し、MCP Registry に登録しました。元の macOS プロジェクトと名前が衝突していたため、Python パッケージ名とコマンド名を mcp_ical / mcp-ical から変更しました。未使用の mcp[cli] エクストラは削除しました。

謝辞とライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。

• 元となった macOS 用 mcp-ical サーバー（Omar D.）。著作権表示は LICENSE に残しています。
• このフォークの基盤となった iCloud CalDAV ポート、zwrong/iCalendar
• python-caldav と Model Context Protocol Python SDK