iCloud Drive Docs MCP server

icloud-docs-mcp

<!-- mcp-name: io.github.js713-lab/icloud-docs-mcp -->

Your agent can find a PDF in iCloud Drive and quote page 3.

Read-only Model Context Protocol server for iCloud Drive. Linux, Windows, or macOS — no Mac, no Spotlight, no ~/Library required.

Source: js713-lab/icloud4u-mcp. The installable package and CLI are named icloud-docs-mcp.

Mail / Calendar / Contacts MCPs already exist. Drive is still the weak spot in the Apple stack if you are not on a Mac. That is the wedge: cross-platform Drive without needing a Mac. It is a utility, not a category.

It lists a folder, searches by filename, downloads files, and extracts text from common documents. There is no default Apple ID, no bundled documents, and no company-specific search logic.

Apple does not publish a third-party iCloud Drive API. This server uses the unofficial pyicloud library. You do not own that pipe. Apple can change an endpoint and this tool is down until someone reverse-engineers it again. Do not promise reliability this repo does not control.

Example:

Find the invoice in iCloud Drive and quote page 3.

What it is not

• Not Mail, Calendar, Contacts, or Notes
• Not a macOS-local Drive MCP (those already use Spotlight / ~/Library)
• Not a hosted / HTTP MCP (it runs locally over stdio)
• Not a 2FA prompt inside the model session
• Not upload, rename, or delete
• Not a reliability SLA. The unofficial client will break.

Disclaimer

This is not an Apple product. Apple does not publish a third-party iCloud Drive API. The unofficial client can break when Apple changes endpoints, and using it may conflict with Apple's terms. Use it at your own risk, locally, on an account you control.

Do not expose this server on the network. Cookiejar files are login credentials: never commit them, never paste them into issues, and never check in .env. See SECURITY.md.

The status tool returns the configured Apple ID and local cache paths so a client can tell whether login succeeded. It never returns a password.

Install

Python 3.10+

From this repository:

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

Install from GitHub:

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

Or, once the package is on PyPI:

pip install icloud-docs-mcp

Copy .env.example to .env and set ICLOUD_USERNAME to your Apple ID. .env is gitignored.

cp .env.example .env

Login (required once)

The MCP process will not wait for a 2FA code. Log in in a real terminal:

export ICLOUD_USERNAME='you@example.com'
icloud-docs-mcp login

You will be prompted for the password and, if Apple asks, a 6-digit device code. A trusted cookiejar is stored under:

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

(~/.local/share/icloud-docs-mcp/... if XDGDATAHOME is unset.)

If a tool returns NEEDLOGIN or NEED2FA, run icloud-docs-mcp login again, then retry.

icloud-docs-mcp status

Tools

Search and read_text are capped so MCP clients with a small result limit are not flooded.

Environment

Shortened. The full README is on GitHub.