iCloud Drive Docs

icloud-docs-mcp

エージェントは iCloud Drive で PDF を見つけ、3 ページ目を引用できます。

iCloud Drive 用の読み取り専用 Model Context Protocol サーバーです。Linux、Windows、macOS に対応しています。Mac も Spotlight も ~/Library も必要ありません。

ソース：js713-lab/icloud4u-mcp。インストール可能なパッケージと CLI の名前は icloud-docs-mcp です。

Mail／Calendar／Contacts の MCP はすでに存在します。Mac を使わない場合、Apple のエコシステムでは Drive が依然として弱点です。そこがこのツールの切り口です。Mac がなくても、クロスプラットフォームで Drive を使えます。 これはユーティリティであり、新しいカテゴリではありません。

フォルダーの一覧表示、ファイル名による検索、ファイルのダウンロード、一般的なドキュメントからのテキスト抽出ができます。デフォルトの Apple ID はなく、ドキュメントも同梱されておらず、企業固有の検索ロジックもありません。

Apple はサードパーティ向けの iCloud Drive API を公開していません。このサーバーは非公式の pyicloud ライブラリを使用しています。この接続経路は管理できません。Apple がエンドポイントを変更すると、このツールは誰かが再びリバースエンジニアリングするまで動作しなくなります。このリポジトリが保証できない信頼性を約束しないでください。

例：

iCloud Drive で請求書を見つけて、3 ページ目を引用してください。

対象外の機能

• Mail、Calendar、Contacts、Notes ではありません
• macOS ローカルの Drive MCP ではありません（すでに Spotlight／~/Library を使用しています）
• ホスト型／HTTP MCP ではありません（ローカルで stdio 経由で実行します）
• モデルセッション内で 2FA プロンプトを表示するものではありません
• アップロード、名前変更、削除には対応していません
• 信頼性の SLA はありません。非公式クライアントは動作しなくなる可能性があります。

免責事項

これは Apple 製品ではありません。Apple はサードパーティ向けの iCloud Drive API を公開していません。Apple がエンドポイントを変更すると、非公式クライアントが動作しなくなる可能性があり、使用すると Apple の利用規約に抵触することがあります。ご自身の責任で、ローカル環境において、ご自身が管理するアカウントで使用してください。

このサーバーをネットワーク上に公開しないでください。Cookiejar ファイルはログイン認証情報です。絶対にコミットしたり、issue に貼り付けたり、.env をチェックインしたりしないでください。SECURITY.md を参照してください。

status ツールは、クライアントがログインの成否を確認できるよう、設定された Apple ID とローカルキャッシュのパスを返します。パスワードは返しません。

インストール

Python 3.10 以降

このリポジトリから：

git clone https://github.com/js713-lab/icloud4u-mcp.git
cd icloud4u-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

GitHub からインストール：

pip install git+https://github.com/js713-lab/icloud4u-mcp.git

または、パッケージが PyPI に公開された後：

pip install icloud-docs-mcp

.env.example を .env にコピーし、ICLOUD_USERNAME に Apple ID を設定します。.env は gitignore に登録されています。

cp .env.example .env

ログイン（初回のみ必須）

MCP プロセスは 2FA コードの入力を待ちません。実際のターミナルでログインしてください。

export ICLOUD_USERNAME='[email protected]'
icloud-docs-mcp login

パスワードの入力を求められます。また、Apple から求められた場合は、デバイスに表示された 6 桁のコードを入力してください。信頼済み Cookiejar は次の場所に保存されます。

$XDG_DATA_HOME/icloud-docs-mcp/<sanitized-username>/

（XDG_DATA_HOME が設定されていない場合は ~/.local/share/icloud-docs-mcp/...。）

ツールが NEED_LOGIN または NEED_2FA を返した場合は、icloud-docs-mcp login を再度実行してから、もう一度試してください。

icloud-docs-mcp status

ツール

ツール	用途
status	セッションの状態。Apple ID とキャッシュのパスを返します。パスワードは返しません。
list_folder	1 つのディレクトリを表示します。パスが空の場合は Drive のルート（または ICLOUD_ROOT）です。
search	ファイル名／パスを検索します。ext は任意で指定でき、結果数には上限があります。
download	Drive のファイルをローカルキャッシュにコピーします。バイト列ではなくパスを返します。
read_text	必要に応じてダウンロードし、pdf、docx、xlsx、txt、csv からテキストを抽出します。

結果数の少ない MCP クライアントに大量の結果が返らないよう、search と read_text には上限があります。

環境変数

変数	必須	説明
ICLOUD_USERNAME	はい	Apple ID。デフォルト値はありません。
ICLOUD_PASSWORD	いいえ	未設定の場合、ログイン CLI が入力を求めます。MCP の環境変数に設定することは避けてください。
ICLOUD_SESSION_DIR	いいえ	Cookiejar ディレクトリの上書き設定。
ICLOUD_DOWNLOAD_DIR	いいえ	ローカルのダウンロードキャッシュ。
ICLOUD_ROOT	いいえ	Drive フォルダーのプレフィックス。すべてのツールはこの範囲内で動作します。

MCP クライアント

デフォルトのコマンド（引数なし）は、stdio で MCP を通信します。

icloud-docs-mcp

Grok

[mcp_servers.icloud_docs]
command = "icloud-docs-mcp"
env = { ICLOUD_USERNAME = "${ICLOUD_USERNAME}" }
startup_timeout_sec = 45
tool_timeout_sec = 180
tool_timeouts = { search = 180, download = 300, read_text = 180 }

Claude Desktop / Cursor

{
  "mcpServers": {
    "icloud-docs": {
      "command": "icloud-docs-mcp",
      "env": {
        "ICLOUD_USERNAME": "<your-apple-id>"
      }
    }
  }
}

クライアントが PATH を引き継がない場合は、venv バイナリの絶対パスを使用してください。

Grok はこのリポジトリの .mcp.json も読み込めます。

grok plugin install js713-lab/icloud4u-mcp --trust

これでサーバーが起動するだけです。マシン上で pip install icloud-docs-mcp（または pip install -e .）と icloud-docs-mcp login も実行する必要があります。

PyPI と公式 MCP Registry にリリースを公開する方法については、PUBLISH.md をご覧ください。

開発

pip install -e ".[dev]"
pytest

テストでは Apple をモックします。CI で iCloud にログインすることは決してありません。CONTRIBUTING.md をご覧ください。

ライセンス

MIT。セキュリティに関する報告：SECURITY.md をご覧ください。

---

CodeCrafter がメンテナンスしています · お問い合わせ：[email protected]。