A
licenseNot graded
qualityD
maintenanceMCP server for iCloud Drive on macOS, enabling Claude to browse, read, search, tag, write, and trash files with safe defaults and automatic handling of iCloud placeholder files.
29 npm
1
MIT
icloud-mcp
Provides tools for interacting with iCloud Drive, including listing folders, retrieving metadata, searching by name or glob, reading and downloading files, uploading and writing files, creating folders, renaming, moving, trashing, listing trash, and restoring items. It talks directly to iCloud and can use hydrated local copies when available.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@icloud-mcp list everything in my Documents folder in iCloud Drive"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
icloud-mcp
MCP server for iCloud Drive. It talks to iCloud directly, so it can list, read and write files whether or not they have been synced to this machine. When a full copy of a file does exist in the local iCloud Drive folder, reads use it and skip the network.
How it decides
Operation | Where it goes |
list, info, search | iCloud (the source of truth). Each entry carries a |
read_file, download | A hydrated local copy if there is one, otherwise streamed from iCloud. |
upload, write_file, mkdir, rename, move, trash, restore | Always iCloud, so every device sees the change at once. |
If the saved session stops working, reads of hydrated local files still succeed
(with a warning); everything else returns one error telling you to sign in again.
Paths are forward-slash and relative to the Drive root, for example
Documents/notes.txt. An empty path is the root. .. is rejected.
Related MCP server: Apple MCP
Tools
Tool | Purpose |
| Apple ID in use, whether the session works, local folder path |
| List a folder |
| Metadata for one item |
| Name search under a folder (substring, or glob with |
| Read a file as text, capped per call, page with |
| Save a file to a local path |
| Upload a local file into a folder |
| Create a text file from a string |
| Create a folder |
| Rename in place |
| Move into another folder |
| Move to the iCloud trash |
| List the trash |
| Restore from the trash by name |
Nothing is deleted permanently.
Setup
Requires Python 3.12+ and uv.
Sign in once at a terminal. The password and 2FA code are typed there and never
stored; only Apple's session cookies are kept, under ~/.icloud-session.
uv run icloud-mcp login
uv run icloud-mcp statusClaude Code plugin
claude plugin marketplace add robworks-code/robworks-claude-code-plugins
claude plugin install icloud-mcp@robworks-claude-code-pluginsManual registration
claude mcp add icloud-mcp -- uv run --project /path/to/icloud-mcp icloud-mcp serveConfiguration
Variable | Default | Meaning |
| the ID saved by | Apple ID to use |
|
| Where session cookies live |
|
| Local sync folder |
|
| Cap for one |
Development
scripts/check.sh # ruff + unit tests (PowerShell: scripts/check.ps1)
scripts/check.sh --live # also runs a round-trip against the real account in _icloud-mcp-testThe unit tests use an in-memory stand-in for the Drive, so they need no account.
Available Tools
14 toolsicloud_downloadC
Save a Drive file to a local path (a directory keeps the file's name). Local copy first.
Inputs: dest (required), path (required), overwrite. Returns: object
icloud_infoA
Metadata for one file or folder, including its local sync state.
Inputs: path (required). Returns: object
icloud_listC
List a Drive folder (default: root). Each entry has path, name, type, size, modified, local.
Inputs: path. Returns: result
icloud_list_trashB
List items in the iCloud Drive trash.
Inputs: no named parameters. Returns: result
icloud_mkdirA
Create a folder (parent must exist). Returns the existing folder if it is already there.
Inputs: path (required). Returns: object
icloud_moveC
Move a file or folder into another folder.
Inputs: path (required), dest_folder (required). Returns: object
icloud_read_fileB
Read a file as UTF-8 text (lossy for binary). Capped per call; page with offset. Local copy first.
Inputs: path (required), offset, max_bytes. Returns: object
icloud_renameC
Rename a file or folder in place.
Inputs: path (required), new_name (required). Returns: object
icloud_restoreC
Restore an item from the trash by name.
Inputs: name (required). Returns: object
icloud_searchB
Find items by name under a folder. Substring match, or a glob if the query has * ? [.
Inputs: query (required), path, max_depth, max_results. Returns: object
icloud_statusA
Report the Apple ID in use, whether the saved iCloud session works, and the local sync folder.
Inputs: no named parameters. Returns: object
icloud_trashA
Move a file or folder to the iCloud trash (recoverable with icloud_restore).
Inputs: path (required). Returns: object
icloud_uploadB
Upload a local file into a Drive folder. Existing names fail unless overwrite is true.
Inputs: local_file (required), name, overwrite, dest_folder. Returns: object
icloud_write_fileA
Create a text file in Drive from a string. Existing names fail unless overwrite is true.
Inputs: path (required), content (required), overwrite. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.5/5.0
Scored across 14 tools
Disambiguation4/5
Most tools target distinct operations, but a few pairs overlap: icloud_read_file vs icloud_download (inline text vs save-to-disk) and icloud_upload vs icloud_write_file (local file vs string content). Descriptions clarify these boundaries, so misselection risk is low but nonzero.
Naming Consistency4/5
All tools share a uniform icloud_ prefix and lowercase snake_case, which is predictable. The only minor deviation is mixing bare nouns (status, list, info) with verb_noun forms (read_file, write_file, list_trash), but it remains readable.
Tool Count5/5
14 tools is well within the ideal range and each one covers a distinct file/folder lifecycle operation. Nothing feels padded or redundant.
Completeness4/5
The surface covers create (mkdir, write_file, upload), read (list, info, search, read_file, download), update (rename, move, overwrite), and delete/restore (trash, list_trash, restore) — strong lifecycle coverage. Minor gaps like copy or share/permission operations exist but are workaroundable.
Maintenance
ActivityNo data
ResponsivenessOutdated data
Related MCP Connectors
Let your agent into iCloud Mail, calendar and contacts. It gets actions, never your password.
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Hosted file storage for agents: upload, list, download, share by link, expire, scratch.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to access iCloud Calendar, Reminders, and Mail with configurable scope and read-only modes.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables an AI assistant to read and search iCloud mail, draft messages (never sent), manage calendar events with a preview/commit gate, and look up contacts via IMAP, CalDAV, and CardDAV.279 npm2MIT
- AlicenseAqualityBmaintenanceEnables read-only iCloud Drive access over MCP, allowing users to browse folders, search filenames, download files, and extract document text.52MIT