← Back to search

@instacodeio/icloud-drive-mcp-server

GitHub Actions Scanned 2d ago

MCP server for iCloud Drive on macOS — Spotlight search, Finder tags, .icloud placeholder handling, and safe Trash-based deletion.

npm ↗
B
89.7 / 100

Versions

0.1.4latest
May 4, 2026
0.1.3
May 4, 2026
0.1.2
May 4, 2026
0.1.1
May 3, 2026
0.1.0
May 3, 2026
PermissionsTool SafetyAuthAnnotationsCode QualityStabilitySpecVuln HistoryAuthorTransparencyCommunity

Tools 9

list_folder
annotations: verified low

List entries in a folder under the iCloud root. Shows name, type, size, mtime, and whether each entry is a not-yet-downloaded .icloud placeholder.

readOnlyHint true idempotentHint false destructiveHint false
read_file
annotations: verified low

Read a file's contents. If it is a .icloud placeholder, triggers `brctl download` and waits for materialization (up to 30s by default).

path string
readOnlyHint true idempotentHint false destructiveHint false
write_file
annotations: verified low

Create or overwrite a file inside the iCloud root. Requires overwrite=true to replace an existing file. Requires ICLOUD_MCP_WRITE=true.

path string content string
readOnlyHint false idempotentHint false destructiveHint false
delete_file
annotations: verified low

Move a file or folder to the macOS Trash (never permanent unlink). Requires ICLOUD_MCP_WRITE=true.

path string
readOnlyHint false idempotentHint false destructiveHint true
download_placeholder
annotations: verified low

Trigger `brctl download` for a .icloud placeholder file and wait for it to materialize, without reading its contents.

path string
readOnlyHint false idempotentHint true
search_files
annotations: verified low

Full-text + filename search via `mdfind`, scoped to ICLOUD_MCP_ROOT (or a sub-scope). Pass raw=true to use a structured Spotlight query string.

query string
readOnlyHint true idempotentHint true destructiveHint false
recent_files
annotations: verified low

Files modified in the last N days (default 7), sorted by mtime descending. Uses Spotlight's content-change-date predicate.

readOnlyHint true idempotentHint true destructiveHint false
get_tags
annotations: verified low

Read macOS Finder tags from a file or folder.

path string
readOnlyHint true idempotentHint true destructiveHint false
set_tags
annotations: verified low

Replace the macOS Finder tag set on a file or folder. Pass an empty array to clear all tags. Requires ICLOUD_MCP_WRITE=true.

path string tags array
idempotentHint true destructiveHint false

Permissions 3

filesystem low
Server uses filesystem capabilities via: fs
shell high
Server uses shell capabilities via: child_process
env_vars low
Server uses env_vars capabilities via: process.env

Scan Findings 0

No scan findings.