iCloud Mail

iCloud Mail MCP

iCloud Mail 用の Model Context Protocol（MCP）サーバーです。LLM が IMAP と SMTP を介して Apple メールを読み取り、検索、整理、送信できます。

すべてお使いのマシン上で実行されるため、認証情報やメールが第三者に渡ることはありません。ネットワーク通信と MIME の解析には、Python 標準ライブラリのみを使用します。

主な機能

• デフォルトでは読み取り専用です。 検索および読み取りツールは SELECT ... readonly と BODY.PEEK を使用するため、メールが知らないうちに既読になったり、移動または削除されたりすることはありません。
• 受信トレイだけでなく、すべてのフォルダを検索します。 返信はメールルールによって別の場所に振り分けられるため、受信トレイだけの検索では見つからないメールも search_all_folders で検索できます。
• 送信前に下書きを作成します。 save_draft は確認用のメッセージを「下書き」に保存します。send_email もありますが、別の明示的な操作です。
• メールを破壊する機能はありません。 メッセージを削除するツールはなく、delete_mailbox はメールが残っているフォルダの削除を拒否します。
• 実際の iCloud MIME に対応しています。 Modified UTF-7 のフォルダ名、quoted-printable、誤った文字セット情報、HTML のみのメッセージ、アクセント付き文字のサーバー側検索に対応します。

必要条件

• Python 3.11 以降、および uv
• 2 ファクタ認証が有効な iCloud アカウント
• アプリ用パスワード — iCloud は IMAP で通常のパスワードを使用できません

はじめに

PyPI に公開された後は、リポジトリのクローンは不要です。

uvx --from icloud-mail-mcp icloud-mcp-setup     # interactive configuration
uvx --from icloud-mail-mcp icloud-mcp           # run the server

ソースから実行する場合：

git clone https://github.com/JulienRabault/icloud-mcp.git
cd icloud-mcp
uv sync
uv run python -m icloud_mcp.setup

セットアップコマンドを実行すると、メールアドレスとアプリ用パスワードの入力を求められ、接続をテストして .env を作成した後、クライアント用の正確な設定ブロックを表示します。

account.apple.com →「サインインとセキュリティ」→「アプリ用パスワード」でアプリ用パスワードを生成してください。

標準設定はほとんどのクライアントで使用できます。

{
  "mcpServers": {
    "icloud-mail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]
    }
  }
}

claude mcp add icloud-mail --scope user -- uv run --directory /path/to/icloud-mcp python -m icloud_mcp

[mcp_servers.icloud-mail]
command = "uv"
args = ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]

MCP サーバーはクライアントの起動時に読み込まれます。設定を編集した後は、クライアントを再起動してください。

ツール

読み取り — これらはメールボックスを変更しません：

書き込み — 明示的な操作です：

メールを破棄するツールはありません。delete_mailboxはメッセージが残っているフォルダーの削除を拒否します。まずメッセージを移動してください。これにより、判断はあなたに委ねられます。

添付ファイルのバイトデータがモデルを経由することはありません。save_attachmentsはファイルを書き込み、そのパスを返します。メールから届いたファイル名はサニタイズされます。これらは信頼できるパスではなく、敵対的な入力です。

リソース

プロンプト

MCP クライアントを使わない自動化

examples/には同じモジュールを使う単独のスクリプトがあります。cronまたはTask Schedulerから実行できます：

uv run python examples/daily_digest.py           # what arrived today
uv run python examples/watch_sender.py acme.com  # exit 1 if nothing new
uv run python examples/waiting_on_reply.py       # threads nobody answered
uv run python examples/auto_file.py --apply      # file mail by rules

すべて--jsonによるパイプ処理に対応しています。examples/README.mdを参照してください。

同梱スキル

skills/mailbox-search/はClaude Codeスキルです。メッセージが存在しないと結論づける前に、すべてのフォルダーを検索するよう徹底します：

cp -r skills/mailbox-search ~/.claude/skills/

ここで対処しているiCloudの特性

iCloudに対して独自のIMAPクライアントを作成する場合に知っておくと便利です：

• SEARCHはUIDを順不同で返します。 RFC 3501は順序を保証しておらず、iCloudは実際にソートされていないリストを返します。応答の末尾を使うと、誤ったメッセージが得られます。まず数値順にソートしてください。
• MOVEもUIDPLUSもありません。 移動にはCOPY + \Deleted + EXPUNGEが必要です。EXPUNGEはフォルダー内のすべての\Deletedメッセージを削除します。move_emailsは、要求されたバッチ以外の削除済みメッセージがフォルダーに残っている場合、実行を拒否します。そうしないと、それらも削除されてしまいます。
• SEARCH CHARSET UTF-8が動作します。 アクセント付きの検索語は、メールボックス全体を対象にサーバー側で検索されます。拒否するサーバー向けのクライアント側フォールバックもあり、応答のfiltered_client_sideでその旨を示します。
• フォルダー名には変更UTF-7（RFC 3501）が使われます。utf7.pyで実装されています。
• 文字セット指定は誤っていることがあります。 宣言された文字セットで本文をデコードできない場合はlatin-1にフォールバックし、text/plainパートがない場合はタグを除去したHTMLにフォールバックします。

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

• 認証情報は.env（gitignore対象）または環境変数に保存し、コードには記述しません。Settings.__repr__はパスワードを省略します。
• メールの内容はデータであり、指示ではありません。サーバーは、受信したメッセージ内に見つかった指示に従って行動しないよう、クライアントに伝えます。
• send_emailとmove_emailsは、会話内でユーザーが正確な内容または正確なメッセージ一覧を承認した後にのみ実行することを想定しています。

開発

uv run pytest -q

ネットワークも認証情報も不要なオフラインテストが49件あります。CIではPython 3.11から3.13を対象に、Linux、macOS、Windowsで実行します。

src/icloud_mcp/
  config.py        env / .env loading
  utf7.py          modified UTF-7 for folder names
  models.py        frozen Pydantic models
  mime.py          header, body and attachment decoding
  imap_client.py   connection, LIST, STATUS, SELECT, FETCH
  search.py        SEARCH criteria, threading, multi-folder search
  smtp_client.py   MIME building, SMTP send, copy to Sent
  attachments.py   attachment extraction, filename sanitising
  drafts.py        APPEND to Drafts
  flags.py         \Seen, \Flagged, \Answered
  move.py          COPY + EXPUNGE with the anti-purge guard
  mailboxes.py     create, rename, delete (empty only)
  organize.py      rule-based filing
  server.py        tools, resources, prompts
  setup_wizard.py  interactive configuration
  cli.py           terminal checks

貢献

イシューやプルリクエストを歓迎します。テストはオフラインで実行できる必要があります。実際のメールボックスを必要とするテストは禁止です。

ライセンス

MIT