icloud-mcp

icloud-mcp

Model Context Protocol を通じて iCloud カレンダー、連絡先、メール にアクセスできます。1 つの Go バイナリが stdio で JSON-RPC を提供し、CalDAV、CardDAV、IMAP、SMTP を介して接続します。

このサーバーは、アプリ用パスワードを使ってヘッドレスで動作します。macOS フレームワーク、 ブラウザーの自動操作、Apple の非公開 API を使わず、リモートプロトコルを使用します。 リリースアーカイブは Linux amd64/arm64 と macOS arm64 に対応しています。CI では Windows amd64 もビルドします。

stdio MCP ホストであれば、プロセス環境を使ってバイナリを起動できます。 バイナリは .env やホスト固有の設定ファイルを読み込みません。

ドメイン	プロトコル	デフォルト
カレンダー	CalDAV HTTPS	常に有効（グローバルな読み取り専用設定がない限り、読み取り＋書き込み）
連絡先	CardDAV HTTPS	ICLOUD_MCP_ENABLE_CONTACTS が設定されるまで無効
メールの読み取り	IMAP TLS	ICLOUD_MCP_ENABLE_MAIL が設定されるまで無効
メールの変更	IMAP	メール機能と ICLOUD_MCP_ENABLE_MAIL_WRITE が有効になるまで無効
メールの送信	SMTP STARTTLS	メール機能、ICLOUD_MCP_ENABLE_MAIL_SEND、宛先ポリシーが有効になるまで無効

リマインダー、メモ、写真、Drive、「探す」、キーチェーン、メッセージ、ホームは サポート対象外です。最新のリマインダーは、このサーバーの CalDAV コネクターを使用しません。

クイックスタート

ビルド済みアーカイブは GitHub Releases から入手できます。 各アーカイブには、バイナリ、ライセンス、サードパーティに関する通知が含まれています。アーカイブの SHA-256 値を リリースのチェックサムファイルと照合してください。各アセットには cosign 署名と証明書も付属しています。

GitHub CLI と Cosign をインストールします。これらのコマンドを実行する前に、GitHub CLI で認証してください。 該当する場合は、platform を linux-arm64 または darwin-arm64 に変更します。

version=$(gh release view --repo ThomasCrouzet/icloud-mcp --json tagName --jq .tagName)
platform=linux-amd64
asset="icloud-mcp-${version}-${platform}.tar.gz"
checksums="icloud-mcp-${version}-checksums.txt"

gh release download "$version" --repo ThomasCrouzet/icloud-mcp \
  --pattern "$asset*" --pattern "$checksums"
grep "  $asset$" "$checksums" | shasum -a 256 -c -
cosign verify-blob \
  --certificate "$asset.pem" \
  --signature "$asset.sig" \
  --certificate-identity "https://github.com/ThomasCrouzet/icloud-mcp/.github/workflows/ci.yml@refs/tags/${version}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "$asset"
tar -xzf "$asset"
./icloud-mcp -version

または、Go 1.26.0 以降を使用します。

go install github.com/ThomasCrouzet/icloud-mcp/cmd/icloud-mcp@latest

1. アプリ用パスワードを作成します。メインの Apple Account パスワードは絶対に使用しないでください。
2. ID とパスワードを、それぞれ別の通常ファイルに保存し、リポジトリの外に置きます。
3. 各ファイルのモードを 0600 以下にし、サイズを最大 4 KiB にします。
4. カレンダーへの読み取り専用アクセス用に環境を設定します。

export ICLOUD_EMAIL='file:///private/path/icloud-email'
export ICLOUD_PASSWORD='file:///private/path/icloud-password'
export ICLOUD_MCP_READ_ONLY=true
export ICLOUD_MCP_DEFAULT_TZ=Europe/Paris   # owner IANA zone; default UTC

5. MCP ホストに、バイナリの絶対パスと環境を登録します。
6. 設定を変更した後は、MCP プロセスを再起動します。

stdio は JSON-RPC を伝送します。stderr はログと変更監査イベントを伝送します。 サーバーが認証情報ファイルを読み込むのは起動時のみです。カレンダーの検出には、 stdio の開始前にネットワークアクセスが必要です。

この設定で公開されるツールは 7 個です。カレンダーの読み取り、ローカルヘルパー、 および icloud_capabilities が含まれます。プロセスは連絡先用やメール用のクライアントを構築しません。

オプションのドメイン（引き続きホストに依存しない export 形式）：

# Contacts reads (writes also need ICLOUD_MCP_READ_ONLY=false)
export ICLOUD_MCP_ENABLE_CONTACTS=true

# Mail reads: IMAP identity may differ from ICLOUD_EMAIL (e.g. [email protected])
export ICLOUD_MCP_ENABLE_MAIL=true
export ICLOUD_MAIL_ADDRESS='file:///private/path/icloud-mail-address'
# Optional separate password; otherwise Mail uses ICLOUD_PASSWORD.
# export ICLOUD_MAIL_PASSWORD='file:///private/path/icloud-mail-password'

# Mail mutation (flags / move / trash); independent of send
export ICLOUD_MCP_ENABLE_MAIL_WRITE=true
export ICLOUD_MCP_READ_ONLY=false

# Mail send: requires exact recipient allowlist even under global read-only
export ICLOUD_MCP_ENABLE_MAIL_SEND=true
export ICLOUD_MCP_SMTP_ALLOWED_RECIPIENTS='[email protected],[email protected]'

12 個の変数からなる完全な仕様については、.env.example を参照してください。

MCP ツール

サーバーが公開するツールは最大 23 個です。無効になっているツールは tools/list に含まれません。無効なドメインについて、プロセスがクライアントを構築することはありません。

数	条件
10	デフォルト：カレンダーの読み取り＋書き込み＋icloud_capabilities
7	グローバル読み取り専用、オプションのドメインはオフ（初回実行時に推奨）
23	連絡先＋メールの読み取り＋変更＋送信、読み取り専用はオフ

ICLOUD_MCP_READ_ONLY=true にすると、カレンダーと連絡先のすべての書き込み、メールのすべての変更、メールの送信が無効になります。無効になっている読み取りドメインが有効になることはありません。

グループ	ツール
グローバル	icloud_capabilities
カレンダーの読み取り	list_calendars, search_events, get_event, find_free_slots, validate_event, calendar_capabilities
カレンダーの書き込み	create_event, update_event, delete_event
連絡先の読み取り	list_address_books, search_contacts, get_contact
連絡先の書き込み	create_contact, update_contact, delete_contact
メールの読み取り	list_mailboxes, search_messages, get_message
メールの変更	set_message_flags, move_message, trash_message
メールの送信	send_message

カレンダーの更新および削除操作は、繰り返しの予定に対応し、強力な If-Match を使用します。連絡先では不透明なアドレス帳 ID を使用し、vCard 3.0 に書き込みます。 メールでは (mailbox, UIDVALIDITY, UID) の ID、PEEK 読み取り、SMTP の厳密な 受信者ポリシーを使用します。move_message は SPECIAL-USE のゴミ箱および迷惑メールの宛先を拒否します。メッセージを削除するには trash_message を使用してください。 set_message_flags は、CONDSTORE が通知されている場合、 protocol_error で安全側に失敗します。これは go-imap beta.8 がタグ付き MODIFIED を検出できないためです。動作に関する詳しい説明は以下を参照してください。 docs/caldav-compatibility.md、 docs/carddav-compatibility.md、 docs/mail-compatibility.md。

UID の作成と更新の冪等性

create_event と create_contact は、client_uid またはその別名 idempotency_key をリソース UID として使用します。その UID がすでに存在する場合、作成処理は conflict を返します。 オブジェクトが黙って上書きされることはありません。

idempotency_key を使って結果をキャッシュするのは、update_event と update_contact のみです。 プロセス内キャッシュには 1,024 件のエントリが保持され、ペイロードあたりの最大サイズは 256 KiB です。 同じキーとパラメーターを指定すると、保存済みの結果が返されます。パラメーターが異なる場合は conflict が返されます。成功および確定的なエラーは 15 分間保持されます。不明な結果は、 プロセスが終了するまで保持されます。保留中の要求は期限切れになりません。

キャッシュが満杯の場合、書き込み前に新しい要求が拒否されます。キーを保持したまま、空きができるまでお待ちください。 応答が不確定だった場合は、新たな更新を行う前に get_event または get_contact を使用してください。 新しいキーやプロセスの再起動によって、前回の書き込みが失敗したと証明されるわけではありません。 新たな更新が必要な場合は、新しい強力な etag を使用してください。

キャッシュの契約と 復旧手順を参照してください。

設定

製品環境変数はちょうど 12 個です。

変数	デフォルト	仕様
ICLOUD_EMAIL	なし	Calendar／Contacts の必須 ID です。file:// に対応しています（通常ファイル、<=4 KiB、モード 0600 以上）。
ICLOUD_PASSWORD	なし	必須の App 用パスワードです。Mail ではフォールバックとして使用します。file:// は上記と同様です。
ICLOUD_MCP_READ_ONLY	false	すべての変更を禁止するキルスイッチです。
ICLOUD_MCP_LOG_LEVEL	info	標準エラー出力のログレベルです。以下の有効な形式を参照してください。
ICLOUD_MCP_DEFAULT_TZ	UTC	オフセットのない Calendar 入力と、繰り返し予定の書き込み時のフォールバックに使用する IANA タイムゾーンです。
ICLOUD_MCP_ENABLE_CONTACTS	false	Contacts ツールです。書き込みには読み取り専用モードをオフにする必要があります。
ICLOUD_MCP_ENABLE_MAIL	false	Mail の読み取りです。Mail アドレスとパスワードが必要です。
ICLOUD_MAIL_ADDRESS	なし	Mail が有効な場合に使用する完全な IMAP／SMTP アドレスです。file:// は上記と同様です。
ICLOUD_MAIL_PASSWORD	ICLOUD_PASSWORD	Mail 専用の App 用パスワード（省略可能）です。file:// は上記と同様です。
ICLOUD_MCP_ENABLE_MAIL_WRITE	false	3 つの IMAP 変更ツールです。
ICLOUD_MCP_ENABLE_MAIL_SEND	false	send_message（Mail の書き込みとは独立しています）。
ICLOUD_MCP_SMTP_ALLOWED_RECIPIENTS	なし	送信を有効にする場合は必須です。完全一致するアドレス、または文字どおりの * を指定します。文字どおりの * を指定すると、起動時に警告が表示されます。可能な限り完全一致するアドレスを使用してください。

ブール値として有効なのは、未設定、0、false、1、true のみです。無効な値を指定すると、起動に失敗します。サーバーはネットワークにアクセスする前に設定を検証します。ホストはこれらの値を文字列として渡す必要があります。たとえば、YAML ではブール値を引用符で囲み、ICLOUD_MCP_READ_ONLY: "false" のように指定してください。引用符のない YAML のブール値は、サーバーの起動前にホスト検証で失敗します。

Mail を有効にせずに Mail の書き込みまたは送信を有効にすると、起動エラーになります。アドレスまたはパスワードを指定せずに Mail を有効にした場合も、起動エラーになります。読み取り専用モードであっても、宛先ポリシーを指定せずに送信を有効にすると、起動エラーになります。

グローバルな読み取り専用モードは書き込みおよび送信のフラグと併用できますが、それらの登録は行われません。

サーバーはログレベルの前後の空白を削除し、大文字と小文字を区別しません。debug または -4、info、warn、warning または 2、error または 4 を指定できます。未設定または認識されない値の場合は、info が使用されます。

バージョンを表示するには -version を使用します。省略可能な -health 127.0.0.1:port フラグを指定すると、ループバックで /healthz と /status が提供されます。どちらのエンドポイントも、ドメインとレート制限を含む JSON を返します。省略可能な -audit-format=json|text フラグで、標準エラー出力に出力する変更監査の形式を選択できます。デフォルトの形式は json です。

日付

• Calendar の入力である start と end は、オフセット付き RFC3339 を受け付けます。オフセットのない現地時刻も受け付け、ICLOUD_MCP_DEFAULT_TZ が適用されます。ユーザーの現地時刻には、オフセットのない値を使用してください。繰り返し予定の作成と、タイムゾーンを明示した予定の作成では、TZID と VTIMEZONE が書き込まれます。繰り返しのない時刻指定の予定を作成する場合、ワイヤー上ではデフォルトで UTC の Z が使用されます。終日の予定の作成では VALUE=DATE が使用されます。
• Calendar の出力では、時刻指定の予定に RFC3339 が使用されます。ICLOUD_MCP_DEFAULT_TZ の明示的な数値オフセットが常に含まれ、Z のみの形式にはなりません。終日の予定の日付には YYYY-MM-DD が使用されます。calendar_capabilities.outputFormat を参照してください。
• Contacts の誕生日：書き込みでは YYYY-MM-DD のみを指定してください。
• Mail の検索：since は指定日を含み、before は指定日を含みません（YYYY-MM-DD）。

セキュリティ（概要）

信頼できないリモートテキストは、ホスト上の LLM に影響を与える可能性があります。ラベルはセキュリティ境界にはなりません。侵害されたモデルは、登録済みのすべてのツールを呼び出せます。このリスクは、すべてのホストおよびベンダーに当てはまります。

• 送信先の固定： カレンダーは caldav.icloud.com および p[0-9]{1,3}-caldav.icloud.com:443 に一致するホストを使用します。連絡先は、連絡先用ホストのうち一致するものを使用します。IMAP は imap.mail.me.com:993 を使用します。SMTP は必須の STARTTLS を使用して smtp.mail.me.com:587 に接続します。接続先は設定できません。サーバーは DAV プロキシ環境変数を無視し、TLS 1.2 以降を検証します。
• 分離： 各ドメインは、認証情報、トランスポート、ダイヤラー、リミッター、セマフォ、プロトコルスタックをそれぞれ個別に持ちます。認証済みの HTTP クライアントが複数のドメインに接続することはありません。
• シークレット： サーバーは、Basic および SASL PLAIN 形式を含むシークレットを削除します。起動時のみの file:// 読み取りには、モード 0600 以上の制限が必要です。サーバーは os/exec やテレメトリを使用しません。起動後にディスクへ書き込むことはありません。
• 監査： 変更ログには、domain、resourceType、プロセス内でのみ有効な HMAC resourceToken が含まれます。生のパス、UID、メールボックス、宛先は一切含まれません。
• 残存リスク： 1 つのプロセスが、有効になっているすべてのドメインの認証情報を保持します。機能フラグを使っても、コンパイル済みコードは削除されません。より強力に分離するには、読み取り専用モードを使用し、有効にするドメインを減らしてください。専用の Mail パスワードまたは別々のプロセスを使用することもできます。

ポリシーの全文：SECURITY.md、docs/security.md。 アーキテクチャ：docs/architecture.md。

制限（概要）

ツールの期限	25s（DAV HTTP 30s）
Stdio / MCP 結果	1 MiB フレーム。結果は 256 KiB。返されるプロトコルエラーには上限があります。
カレンダー	検索範囲：366 日。結果：合計 400 件、カレンダーごとに 2,500 件、カレンダー全体でマテリアライズされる項目は 10,000 件。繰り返し予定：展開 2,000 回、シリーズごとに 100k ステップ、検索ごとに 250k ステップ。レート：読み取りは毎分 60 回、書き込みは毎分 20 回。同時実行数：読み取り 4 件、書き込み 2 件。
連絡先	アドレス帳 100 件。概要 100 件。スキャンするカード 2000 件。レート：読み取りは毎分 60 回、書き込みは毎分 20 回。同時実行数：4 件。
メール	レート：読み取りは毎分 60 回、変更は毎分 20 回、送信は毎分 20 回。セマフォ：読み取り 2 件、変更 1 件、送信 1 件。変更や送信の再試行はありません。
書き込み	カレンダーの PUT/DELETE、連絡先への書き込み、IMAP の変更、SMTP の自動再実行は行いません。結果が不明な場合は outcome_unknown を使用します。

サーバーは起動時にカレンダーを検出し、連絡先は初回使用時に検出します。呼び出しごとに、新しい IMAP または SMTP セッションを使用します。レート、パーサーの予算、再試行ルールについては、以下のドキュメントを参照してください。 docs/testing.md、docs/architecture.md。

複数アカウント

1 つのプロセスが保持できる iCloud ID は 1 つです。ID ごとに別のプロセスを起動してください。 各プロセスには個別の環境変数と、必要に応じてヘルスポートを割り当ててください。 ホストとの統合を参照してください。

依存関係

Go 1.26.0 以降を使用してください。このプロジェクトにはモジュールが 1 つあり、直接依存関係はちょうど 10 個です。直接依存関係を追加する場合は、ここにその理由を記載してください。

依存関係	正確なバージョン	理由
github.com/emersion/go-webdav	v0.7.0	CalDAV の基本機能です。検出と条件付き操作は引き続き手書きで実装しています。
github.com/emersion/go-ical	v0.0.0-20250609112844-439c63cef608	iCalendar の解析／エンコード
github.com/mark3labs/mcp-go	v1.2.0	MCP の stdio、スキーマ、JSON-RPC
github.com/teambition/rrule-go	v1.8.2	タイムゾーンを保持する、範囲を限定した繰り返し処理
golang.org/x/time	v0.16.0	ドメインごとのレートリミッター
github.com/emersion/go-vcard	v0.1.0	vCard 3.0／4.0 の読み込み、3.0 の書き込み
github.com/emersion/go-imap/v2	v2.0.0-beta.8	internal/mail/imapadapter 経由の IMAP
github.com/emersion/go-message	v0.18.2	MIME／プレーンテキストの範囲制限
github.com/emersion/go-smtp	v0.25.0	SMTP + STARTTLS
github.com/emersion/go-sasl	v0.0.0-20241020182733-b788ff22d5a6	STARTTLS 後の SASL PLAIN

ビルドとテスト

make build        # local host binary, VERSION defaults to dev
make test         # go test ./... -race -cover
make lint         # go vet + pinned golangci-lint
make release VERSION=v1.2.3      # packaged linux/arm64, digest-pinned Go 1.26.10 image
make release-all VERSION=v1.2.3  # packaged linux/amd64, linux/arm64, darwin/arm64 (host Go)
make install      # host-compatible build to INSTALL_DIR (default ~/.local/bin)

リリースターゲットには、クリーンな作業ツリーと v1.2.3 のようなバージョンが必要です。既存のリリース成果物を置き換えることはありません。アーカイブには、バイナリ、LICENSE、THIRD_PARTY_NOTICES.md が含まれます。dist/ ディレクトリには SHA-256 チェックサムファイルも含まれます。GitHub のタグリリースでは、そのタグに対する CI と gitleaks が成功した後にのみ make release-all を実行します。Go 1.26.10 を使用し、check-latest は無効にしています。

ローカルの make release では、linux/arm64 向けにダイジェスト固定のコンテナパスを使用します。リリース成果物には cosign のキーレス署名が含まれます。-version はまずリリースの ldflags 値を使用します。この値がない場合は、Go モジュールのビルド情報を使用します。そのため、go install ...@version はモジュールのバージョンを報告します。

CI では、フォーマット、競合テスト、脆弱性、シークレット、公開テキスト、マルチアーキテクチャビルドをチェックします。カバレッジの下限と 20 MiB のバイナリサイズ制限を適用します。リリースタグの CI では、すべてのパーサーパッケージに対してファズスモークテストを実行します。手動のワークフローオプションでも同じテストを実行できます。 ライブテストには integration ビルドタグと、明示的なドメイン／書き込みゲートが必要です。CI では実行されません。テストを参照してください。

フィクスチャのみを使ったプロトコルのエビデンスを出力するには、リポジトリ外の絶対パスを指定してください。

make protocol-evidence EVIDENCE_DIR=/external/path

ランナーは、共有の MCP 登録コードと stdio 起動コードを含む cmd/icloud-mcp のテストから実行ファイルをビルドします。また、インプロセスで冪等性と繰り返しのシナリオを実行します。トランスクリプト、実行メタデータ、ソースリビジョン、作業中の差分、フィクスチャの SHA-256 値、結果をリポジトリ外に保存します。 CI はランナー上でこのエビデンスを生成し、ジョブの終了後に破棄します。 CI は GitHub にレポートをアップロードしたり、アーカイブしたりしません。これらのチェックでは合成フィクスチャを使用しており、iCloud とのライブ互換性を証明するものではありません。

ドキュメント

ドキュメント	内容
ホスト連携	Stdio の設定、シークレットファイル、ヘルスチェック、複数アカウント、呼び出し側の動作
エラーコード	再試行ルールと変更操作からの復旧
アーキテクチャ	起動、ドメイン境界、並行処理、更新の冪等性
CalDAV 互換性	カレンダーの検出、条件付き書き込み、繰り返し、制限
CardDAV 互換性	連絡先の検出、vCard のサポート、検索、条件付き書き込み
メール互換性	IMAP セッション、メッセージの識別、変更操作、SMTP 送信
セキュリティポリシー と実装	脅威モデル、報告、技術的な対策
テスト	ローカルチェック、プロトコルのエビデンス、CI、ライブ連携ゲート
コントリビューション	開発、執筆、テストポリシー、サポート
変更履歴	リリース履歴

謝辞

カレンダーツールの構造といくつかのパターンは、 github.com/roygabriel/mcp-icloud-calendar （MIT、著作権 2026 Gabe）から着想を得ています。コードはコピーせず、書き直しました。このサーバーでは、 ドメインごとに厳格な送信制御、秘匿化、上限付きパーサー、条件付き変更、 連絡先、メールを追加し、テレメトリーは行いません。

貢献

CONTRIBUTING.md を参照してください。プルリクエストを作成する前に、gofmt、make test、make lint を実行してください。

ライセンス

MIT です。LICENSE および third-party notices を参照してください。