Which integrations are available for this server?

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.

How do I use icloud-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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 `local` field: `hydrated`, `placeholder`, or `absent`.
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
`icloud_status`	Apple ID in use, whether the session works, local folder path
`icloud_list`	List a folder
`icloud_info`	Metadata for one item
`icloud_search`	Name search under a folder (substring, or glob with `*` `?` `[`)
`icloud_read_file`	Read a file as text, capped per call, page with `offset`
`icloud_download`	Save a file to a local path
`icloud_upload`	Upload a local file into a folder
`icloud_write_file`	Create a text file from a string
`icloud_mkdir`	Create a folder
`icloud_rename`	Rename in place
`icloud_move`	Move into another folder
`icloud_trash`	Move to the iCloud trash
`icloud_list_trash`	List the trash
`icloud_restore`	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 status

Claude Code plugin

claude plugin marketplace add robworks-code/robworks-claude-code-plugins
claude plugin install icloud-mcp@robworks-claude-code-plugins

Manual registration

claude mcp add icloud-mcp -- uv run --project /path/to/icloud-mcp icloud-mcp serve

Configuration

Variable	Default	Meaning
`ICLOUD_APPLE_ID`	the ID saved by `login`	Apple ID to use
`ICLOUD_SESSION_DIR`	`~/.icloud-session`	Where session cookies live
`ICLOUD_LOCAL_ROOT`	`%USERPROFILE%\iCloudDrive` on Windows, `~/Library/Mobile Documents/com~apple~CloudDocs` on macOS	Local sync folder
`ICLOUD_MAX_READ_BYTES`	`200000`	Cap for one `icloud_read_file` call

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-test

The unit tests use an in-memory stand-in for the Drive, so they need no account.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Layven AOAuth
io.layven
Shared drive for your agents and teammates.
Cloud Storage File Systems
141
hashn B
com.hashn
Private shared file system for agents: workspaces, invites, shared files.
File Systems Agent Orchestration
281
NoMac A
app.nomac
Cloud macOS with Xcode for AI agents: run commands, build, test and ship iOS apps.
CI/CD & DevOps Code Execution Developer Tools
381
uldl
sh.uldl
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
File Systems Cloud Storage Agent Orchestration
2

Related MCP Servers

@instacodeio/icloud-drive-mcp
File Systems Cloud Storage Search
InstaCode
A
license
Not graded
quality
C
maintenance
MCP 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.
Updated 2 months ago (2026-08-04 12:10 UTC)
13 npm
1
MIT
Apple MCP
Email Calendar Management Note Taking
thetaroot
A
license
Not graded
quality
C
maintenance
Enables AI agents to access iCloud Calendar, Reminders, and Mail with configurable scope and read-only modes.
Updated a month ago (2026-08-23 06:57 UTC)
1
MIT
iCloud MCP
Email Calendar Management
russellkmoore
A
license
Not graded
quality
B
maintenance
Enables 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.
Updated 4 days ago (2026-09-29 17:37 UTC)
38 npm
MIT
icloud-docs-mcp
Cloud Storage
js713-lab
A
license
A
quality
A
maintenance
Enables read-only iCloud Drive access over MCP, allowing users to browse folders, search filenames, download files, and extract document text.
Updated 18 days ago (2026-09-15 11:27 UTC)
5
2
MIT