Apple Files

Apple Files MCP

用于在 macOS 上处理文件、Finder 相关操作和 iCloud Drive 工作流的本地 MCP 服务。

功能

• 列出允许访问的文件根目录
• 查看目录内容
• 按名称搜索文件和文件夹
• 读取 UTF-8 文本文件
• 查看文件元数据
• 列出最近的文件
• 在默认应用中打开路径
• 在 Finder 中显示路径
• 读取和写入 Finder 标签
• 列出最近访问的位置
• 报告本地 iCloud Drive 的可用性
• 创建文件夹
• 移动或重命名路径
• 删除文件或空文件夹
• 资源：files://allowed-roots、files://recent、files://recent-locations、files://icloud-status
• 提示词：files_prepare_attachment、files_organize_workspace
• 为上下文受限的客户端提供工具发现辅助工具 search_tools 和 get_tool_info

在这台 Mac 上安装

uvx apple-files-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

在 AI Agent 中安装

{
  "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"
      }
    }
  }
}

如果要从克隆的仓库运行，请使用 /path/to/Apple-MCPs/AppleFiles-MCP/start.sh 作为命令，并将 args 留空。

Claude Code：

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

--scope user 会让所有项目都能使用该服务。若要通过仓库的 .mcp.json 与单个仓库共享，请改用 --scope project。

传输方式

默认且推荐的传输方式是 stdio。设置 APPLE_FILES_MCP_TRANSPORT=streamable-http（可选设置 APPLE_FILES_MCP_HOST 和 APPLE_FILES_MCP_PORT）即可改用 Streamable HTTP 提供服务。

提示词使用说明

• tools/list 会返回完整的 Files 工具列表。上下文受限的客户端可以先使用 search_tools，再针对所需的 Files 工具调用 get_tool_info。
• 用户提到本地文件或附件时，请先于 Mail、Messages、Notes 或 Shortcuts 使用此服务。
• Finder 风格的工作流、iCloud Drive 路径和文件标签操作请使用此服务，不要回退到原始 shell 命令。
• 发送或附加文件前，请确认准确路径。
• 为确保安全，请将 APPLE_FILES_MCP_ALLOWED_ROOTS 的范围设得尽可能小。
• 若希望助手处理 iCloud 文档，请包含本地 iCloud Drive 根目录。
• 对需要创建和移动文件的助手工作流，请使用 APPLE_FILES_MCP_SAFETY_MODE=safe_manage；仅在需要删除文件时才使用 full_access。

健康检查与恢复

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

启动检查清单

• 将 uvx apple-files-mcp（或克隆仓库中的 AppleFiles-MCP/start.sh）添加到 MCP 客户端
• 重新加载或重新连接客户端，以便将 Files 工具列表加载到上下文中
• 首先调用 files_health
• 如果访问权限看起来不正确，请调用 files_permission_guide
• 在执行任何文件修改工作流前，确认 APPLE_FILES_MCP_ALLOWED_ROOTS

移动操作会拒绝已存在的目标，包括文件、文件夹和符号链接。移动或删除符号链接时，操作对象是链接本身；读取操作仍会解析目标并强制执行允许的根目录限制。文本读取接受 1 到 10485760 之间的 max_bytes，仅读取该大小限制内的文件前缀，并拒绝读取非普通文件。