MCPInstall
Apple Files logo

Apple Files

by JonathanRReed 35 stars jonathanrreed/apple-mcps

Inspect and manage local files and folders inside allowed roots on macOS.

READMEHEAD

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.

More File Systems MCP servers

Similar servers from the same category.

Flatfile logo

Flatfile

flatfilers

Provides direct access to Flatfile's data migration platform for managing spaces, workbooks, sheets, jobs, users, and data operations without leaving your conversation context.

filesystem
Filesystem logo

Filesystem

modelcontextprotocol

Secure file operations with configurable access controls

file-operationsfile
obituary logo

obituary

woodfishhhh

Gives the files an AI agent writes an expiry date: debug scripts, logs and screenshots are buried in a restorable graveyard when their lifespan runs out and can be brought back for seven days; Git-tracked files are never touched.

File Systems
large-file-mcp logo

large-file-mcp

willianpinho

Large-file handling with chunking, navigation, streaming, regex search and LRU caching.

File Systems