icloud-mcp

icloud-mcp

IMAP と CalDAV を介して、AI アシスタントに iCloud メールとカレンダーへの読み取り専用アクセスを提供する Model Context Protocol サーバーです。認証情報は OS のキーチェーン（デフォルトでは macOS Keychain）に保存され、設定ファイルやリポジトリには保存されません。

デフォルトでは iCloud を対象としていますが、すべてのエンドポイントを変更できるため、標準的な IMAP/CalDAV プロバイダーであれば利用できます。

ステータス

デフォルトでは読み取り専用で、書き込みは明示的なオプトインが必要です。 メール、カレンダー、連絡先は、変更を加える機能を使わずに一覧表示、検索、閲覧できます。IMAP 接続は読み取り専用で開かれ、本文は BODY.PEEK[] で取得されるため、メッセージが既読になることもありません。

変更を加えるツールには、メール（send_mail、reply_mail、forward_mail）、カレンダー（create_event、update_event、delete_event）、連絡先（create_contact、update_contact、delete_contact）がありますが、ICLOUD_ENABLE_WRITES=1 を設定しない限り、すべて無効です。また、有効にした場合でも、各書き込みの実行前にインタラクティブな確認（MCP elicitation）が必要です。書き込み（オプトイン）を参照してください。

書き込み（オプトイン）

変更操作には、次の 2 つのゲートが設けられています。

1. 運用者スイッチ — サーバーの環境変数に ICLOUD_ENABLE_WRITES=1 が設定されていない場合、書き込みツールは説明付きのエラーを返します。
2. 操作ごとの確認 — 有効にすると、各書き込みツールは実行前にクライアントへコールバックし、実行する操作の内容を確認します。破壊的な操作（イベント／連絡先の削除）も同様に制限されます。追加の強制フラグはなく、同じ確認が必要です。

iCloud が発行する、IMAP、SMTP、CalDAV、CardDAV を対象とした単一のアプリ用パスワードには、書き込み専用のスコープはありません。そのため、書き込みの安全性は構造的に確保されています。メールは独立した新しい SMTP 接続で送信され（読み取り処理の IMAP クライアントには送信機能がありません）、オプトインフラグと確認によってすべての変更操作が保護されます。

インストール

pip install icloud-mcp

インストールせずに実行することもできます。サーバーを必要に応じて起動する MCP クライアントに便利です。

uvx icloud-mcp

GitHub から、まだリリースされていない最新コードを直接インストールするには、次のようにします。

pip install git+https://github.com/eodozzy/icloud-mcp

ローカルで開発する場合は、次のようにします。

git clone [email protected]:eodozzy/icloud-mcp
cd icloud-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[test]"

Python 3.11 以降が必要です。

認証情報

Apple ID 用のアプリ用パスワードを生成し（メインのパスワードは絶対に使用しないでください）、キーチェーンに保存します。

# macOS
security add-generic-password -a "[email protected]" -s "icloud-mcp" -w "xxxx-xxxx-xxxx-xxxx"

その他のプラットフォームでは、クロスプラットフォームの keyring ライブラリが使用されます。keyring set icloud-mcp [email protected] はどの環境でも使用できます。

ユーザー名は ICLOUD_USERNAME 環境変数から取得されます。パスワードは次の順序で解決されます。

1. OS のキーチェーン（ICLOUD_KEYRING_SERVICE。デフォルトは icloud-mcp。およびユーザー名）
2. ICLOUD_APP_PASSWORD 環境変数（フォールバック）

既存のキーチェーンエントリー（例：my-icloud という名前のもの）を再利用するには、ICLOUD_KEYRING_SERVICE=my-icloud を設定します。

設定

ICLOUD_USERNAME を設定してください（必須）。それ以外はすべて任意です。エンドポイントやタイムゾーンのオーバーライドについては、.env.exampleに一覧があります。

MCP クライアントへの登録

このサーバーは stdio 経由で MCP と通信します。クライアントが icloud-mcp コマンドをサブプロセスとして起動し、stdin/stdout 経由で通信します。クライアントへの「インストール」とは、実行するコマンドと渡す環境変数をクライアントに指定することです。パスワードはキーチェーンに保存されたままで、クライアントの設定には保存されません。

icloud-mcp が PATH にない場合（例：仮想環境にインストールした場合）は、ランチャーの絶対パスを指定してください。例：/path/to/repo/.venv/bin/icloud-mcp。

Claude Code

claude mcp add icloud \
  --env [email protected] \
  --env ICLOUD_KEYRING_SERVICE=icloud-mcp \
  -- icloud-mcp

続いて claude mcp list を実行して確認します。現在のプロジェクトだけでなく、すべてのプロジェクトで利用できるようにするには、-s user を追加してください。

Claude Desktop

サーバーを Claude Desktop の設定ファイルに追加します。macOS では次のとおりです。

~/Library/Application Support/Claude/claude_desktop_config.json

（Windows の場合：%APPDATA%\Claude\claude_desktop_config.json。）

ファイルを開く最も簡単な方法は、設定 → 開発者 → 設定を編集です。ファイルにすでにある内容と並べて mcpServers キーを追加します。2 つ目のトップレベルの { ... } オブジェクトを貼り付けないでください。JSON が無効になります。

{
  "mcpServers": {
    "icloud": {
      "command": "icloud-mcp",
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_KEYRING_SERVICE": "icloud-mcp"
      }
    }
  }
}

ファイルにほかのキーがすでにある場合は、mcpServers を同階層のキーとして追加します（キー間のカンマを忘れないでください）。

{
  "someExistingSetting": "...",
  "mcpServers": { "icloud": { "...": "..." } }
}

次に、Claude Desktop を完全に終了して（ウィンドウを閉じるだけでなく、⌘Q を押して）、再起動します。サーバーが ローカル MCP サーバー として表示され、そのツールを利用できるようになります。

注意：

• 初回の呼び出し時に、キーチェーンへのアクセス許可を求められます。 macOS から icloud-mcp がキーチェーン項目を読み取る許可を求められたら、繰り返し表示されないように常に許可をクリックしてください。
• Claude Desktop は設定を保存する際に、このファイルを書き換えることがあります。 認識できない手動追加キーが削除される場合があります。ほかの設定を変更した後にサーバーが表示されなくなった場合は、mcpServers ブロックを再度追加してください。

ツールとリソース

ツール（モデルから呼び出されます）：

ツール	説明
list_mail	フォルダーを新しい順に一覧表示します（既定は INBOX）。since_date を指定できます
search_mail	受信トレイ（または指定したフォルダー）を全文検索します
list_folders	利用可能な IMAP メールボックスのフォルダー名を一覧表示します
get_message	UID で指定したメッセージを本文全体とともに取得します
list_events	指定した期間のカレンダーイベントを一覧表示します
search_events	指定した期間内で、タイトルに指定したテキストを含むイベントを検索します
list_calendars	すべてのカレンダー名を一覧表示します
list_contacts	アドレス帳の連絡先（名前、メールアドレス、電話番号、組織）を一覧表示します
search_contacts	名前、組織、メールアドレスからテキストに一致する連絡先を検索します
send_mail ⚠️	プレーンテキストのメールを送信します
reply_mail ⚠️	UID で指定したメッセージに返信します（元のメッセージを引用します。reply_all は任意です）
forward_mail ⚠️	UID で指定したメッセージを新しい宛先に転送します
create_event ⚠️	カレンダーイベントを作成します
update_event ⚠️	UID で指定したイベントを編集します（渡したフィールドのみ）
delete_event ⚠️	UID で指定したイベントを削除します
create_contact ⚠️	新しい連絡先を作成します
update_contact ⚠️	UID で指定した連絡先を編集します（既存の vCard に統合します）
delete_contact ⚠️	UID で指定した連絡先を削除します

⚠️ 書き込みツールを使用するには ICLOUD_ENABLE_WRITES=1 が必要で、各操作の確認が求められます。書き込み（オプトイン）を参照してください。

リソース（受動的なコンテキスト）：

URI	説明
icloud://mail/inbox/recent	受信トレイの最新メッセージ
icloud://calendar/today	今日と明日のイベント

動作に関する注意

• ヘッダーが空または存在しない場合： Subject ヘッダーが存在しない、または存在していても空白のメッセージは (no subject) と表示されます。From が空白または存在しない場合は (unknown) と表示されます。（メールによっては、件名行自体がないのではなく空になっています。どちらの場合も正規化されます。）
• スニペットでは text/plain パートが優先されます。HTML のみのメールではタグが取り除かれ（<style>／<script>／<head> の内容は破棄されます）、読みやすいプレビューが表示されます。
• 二重にラップされた本文： 一部の送信者（USPS Informed Delivery など）は、デコードされた本文の先頭に余分な MIME ヘッダーブロックを埋め込むことがあります。先頭の Content-*／MIME-Version ヘッダーブロックは取り除かれるため、これらのヘッダーがスニペットや本文に混入することはありません。
• since_date は日付単位で、IMAP サーバーのタイムゾーン（iCloud では UTC）で評価されます。そのため、今日を指定した since_date には、現地時間で昨日の遅い時間に届いたメッセージが含まれることがあります。

開発

.venv/bin/pytest            # run the fixture-based test suite (no live account)
.venv/bin/mcp dev -m icloud_mcp.server   # interactive MCP Inspector

セキュリティに関する注意事項

• アプリ専用パスワードは OS のキーチェーン内にのみ保存されます。.env に保存したり、コミットしたりすることはありません。
• 読み取りアクセス（メール、カレンダー、連絡先）では、データを変更できません。IMAP セッションは読み取り専用で開かれます。
• 書き込みはデフォルトで無効です。ICLOUD_ENABLE_WRITES=1 に設定し、さらに各操作で対話形式の確認を行う必要があります。また、メールは読み取り処理経路から分離された別の SMTP 接続経由で送信されます。
• アプリ専用パスワードは、Apple ID に影響を与えることなく、appleid.apple.com からいつでも取り消せます。

ライセンス

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

---

Apple Inc. とは提携、承認、スポンサー関係にありません。iCloud は Apple Inc. の商標です。