iCloud Drive Docs

icloud-docs-mcp

你的 Agent 可以在 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，Drive 仍是 Apple 生态中的短板。这正是切入点：无需 Mac 即可跨平台使用 Drive。 这是一款实用工具，而非一个类别。

它可以列出文件夹、按文件名搜索、下载文件，并从常见文档中提取文本。它没有默认 Apple ID、不附带文档，也没有针对特定公司的搜索逻辑。

Apple 不会发布第三方 iCloud Drive API。本服务使用非官方的 pyicloud 库。你无法控制这条连接。Apple 可以更改某个端点，在有人再次对其进行逆向工程之前，这个工具就会停止工作。不要承诺本仓库无法保证的可靠性。

示例：

在 iCloud Drive 中找到发票，并引用第 3 页的内容。

它不是什么

• 不是 Mail、Calendar、Contacts 或 Notes
• 不是 macOS 本地的 Drive MCP（此类 MCP 已经使用 Spotlight / ~/Library）
• 不是托管式 / HTTP MCP（它在本地通过 stdio 运行）
• 不是模型会话中的双重身份验证提示
• 不支持上传、重命名或删除
• 不提供可靠性 SLA。非官方客户端可能会失效。

免责声明

这不是 Apple 产品。Apple 不会发布第三方 iCloud Drive API。Apple 更改端点时，非官方客户端可能会失效；使用它也可能违反 Apple 的条款。风险由你自行承担；请在本地使用，并仅用于你控制的帐户。

请勿将此服务暴露在网络上。Cookiejar 文件属于登录凭据：切勿提交它们、将它们粘贴到问题中，或签入 .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 进程不会等待输入双重身份验证代码。请在真实终端中登录：

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	列出一个目录。空路径表示 Drive 根目录（或 ICLOUD_ROOT）。
search	按文件名 / 路径查询，可选 ext，结果数量有限。
download	将 Drive 文件复制到本地缓存。返回路径，不返回字节内容。
read_text	如有需要则先下载；从 pdf、docx、xlsx、txt、csv 中提取文本。

search 和 read_text 都限制了结果数量，以免向结果限制较小的 MCP 客户端返回过多内容。

环境变量

变量	必需	含义
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]。