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_toolsandget_tool_infofor context-constrained clients
Install On This Mac
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/listreturns the full Files tool surface. Context-constrained clients can usesearch_toolsfirst, thenget_tool_infofor 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_ROOTSnarrow 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_managefor assistant workflows that need create and move, andfull_accessonly for delete workflows.
Health And Recovery
files_healthfiles_permission_guidefiles_list_allowed_rootsfiles_get_icloud_statusfiles_list_recent_locationsfiles_get_tags
Launch Checklist
- Add
uvx apple-files-mcp(or a clone'sAppleFiles-MCP/start.sh) to your MCP client - Reload or reconnect the client so the Files tool surface is loaded into context
- Call
files_healthfirst - If access looks wrong, call
files_permission_guide - Confirm
APPLE_FILES_MCP_ALLOWED_ROOTSbefore 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.
