Apple Files

Apple Files MCP

Local MCP server for file, Finder-adjacent, and iCloud Drive workflows on macOS.

Capabilities

• list allowed file roots
• inspect directory contents
• search files and folders by name
• read UTF-8 text files
• inspect file metadata
• list recent files
• open a path in the default app
• reveal a path in Finder
• read and write Finder tags
• list recent locations
• report local iCloud Drive availability
• create folders
• move or rename paths
• delete files or empty folders
• resources: files://allowed-roots, files://recent, files://recent-locations, files://icloud-status
• prompts: files_prepare_attachment, files_organize_workspace
• tool discovery helpers search_tools and get_tool_info for context-constrained clients

Install On This Mac

Quick start (uvx, from PyPI)

With uv installed:

uvx apple-files-mcp

No clone, no venv management.

From a clone

git clone https://github.com/JonathanRReed/Apple-MCPs.git

cd Apple-MCPs uv sync --all-packages

This builds one workspace environment with every server's entry point in .venv/bin (for example .venv/bin/apple-files-mcp). You can also point an MCP client at AppleFiles-MCP/start.sh, which prefers uv run and falls back to a plain venv bootstrap (Python 3.11+ required).

Install In AI Agents

{

"mcpServers": { "apple-files": { "command": "uvx", "args": ["apple-files-mcp"], "env": { "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs", "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage" } } } }

Running from a clone instead? Use /path/to/Apple-MCPs/AppleFiles-MCP/start.sh as the command with empty args.

Claude Code:

claude mcp add --transport stdio --scope user apple-files -- uvx apple-files-mcp

--scope user makes the server available in every project. To share it with one repository through its .mcp.json instead, use --scope project.

Transport

stdio is the default and recommended transport. Set APPLE_FILES_MCP_TRANSPORT=streamable-http (with optional APPLE_FILES_MCP_HOST and APPLE_FILES_MCP_PORT) to serve Streamable HTTP instead.

Prompting Notes

• tools/list returns the full Files tool surface. Context-constrained clients can use search_tools first, then get_tool_info for the Files tool they need.
• Use this server before Mail, Messages, Notes, or Shortcuts when the user references a local file or attachment.
• Use this server for Finder-style workflows, iCloud Drive paths, and file tagging, not raw shell fallbacks.
• Confirm the exact path before sending or attaching a file.
• Keep APPLE_FILES_MCP_ALLOWED_ROOTS narrow for safety.
• Include the local iCloud Drive root when you want the assistant to work with iCloud documents.
• Use APPLE_FILES_MCP_SAFETY_MODE=safe_manage for assistant workflows that need create and move, and full_access only for delete workflows.

Health And Recovery

• files_health
• files_permission_guide
• files_list_allowed_roots
• files_get_icloud_status
• files_list_recent_locations
• files_get_tags

Launch Checklist

• Add uvx apple-files-mcp (or a clone's AppleFiles-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Files tool surface is loaded into context
• Call files_health first
• If access looks wrong, call files_permission_guide
• Confirm APPLE_FILES_MCP_ALLOWED_ROOTS before any file mutation workflow

Moves reject an existing destination, including files, folders and symbolic links. An allowed root, or a folder that contains one, cannot be moved or deleted. Moving or deleting a symbolic link operates on the link itself; reads still resolve the target and enforce allowed roots. Text reads accept max_bytes from 1 through 10485760, read only that bounded prefix, and reject non-regular files.