Apple System

Apple System MCP

用于提供 macOS 系统上下文、如实报告专注模式支持情况、读取与助手相关的设置、显式写入设置，以及有限范围 GUI 回退自动化的本地 MCP 服务。

功能

• 电池状态
• 最前台应用
• 正在运行的应用
• 剪贴板读取和写入
• 本地通知
• 打开应用
• 外观设置
• 辅助功能设置
• Dock 设置
• Finder 设置
• 如实报告专注模式支持情况
• 综合系统上下文快照
• 外观模式写入
• Finder 可见性和栏设置写入
• Dock 写入控制：自动隐藏和最近使用的应用
• 辅助功能写入：减少动态效果、增强对比度和降低透明度
• GUI 回退工具：点击菜单、按键、输入文本、点击按钮和选择弹出选项
• 通过 defaults export 检查偏好设置域
• 资源：system://status、system://applications、system://settings、system://context
• 提示词：system_capture_context
• 面向上下文受限客户端的工具发现辅助工具 search_tools 和 get_tool_info

在此 Mac 上安装

uvx apple-system-mcp

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

在 AI Agent 中安装

{
  "mcpServers": {
    "apple-system": {
      "command": "uvx",
      "args": ["apple-system-mcp"],
      "env": {
        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage"
      }
    }
  }
}

如果从克隆的仓库运行，则将 /path/to/Apple-MCPs/AppleSystem-MCP/start.sh 设为命令，并将 args 留空。

Claude Code：

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

--scope user 会让所有项目都能使用此服务。若要通过仓库的 .mcp.json 将其共享给单个仓库，则使用 --scope project。

传输方式

默认且推荐使用 stdio 传输方式。设置 APPLE_SYSTEM_MCP_TRANSPORT=streamable-http（可选设置 APPLE_SYSTEM_MCP_HOST 和 APPLE_SYSTEM_MCP_PORT）即可改用 Streamable HTTP 服务。

提示词说明

• tools/list 会返回完整的 System 工具列表。上下文受限的客户端可以先使用 search_tools，再通过 get_tool_info 获取所需的 System 工具信息。
• 用户当前的桌面上下文与任务相关时，请使用此服务。
• 执行可能打断用户的操作前，先读取电池状态和最前台应用。
• 在提示词或端到端检查中回退到原始 defaults read 前，请先使用设置工具。
• 使用 APPLE_SYSTEM_MCP_SAFETY_MODE=safe_manage 以满足助手级操作需求。
• 仅在只读审计或仅提供上下文的部署中使用 safe_readonly。
• 将 GUI 回退的使用范围控制在最小。优先使用原生应用域 MCP，再使用显式 System 工具，只有原生支持缺失时才使用 GUI 工具。GUI 输入要求目标应用位于 APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS 中（参见 GUI 输入允许列表）。
• 专注模式报告尽力而为，并如实反映支持情况。在未签名的本地安装中，如果 macOS 未能以可靠方式提供通知中心历史记录，此服务不会声称支持该功能。

健康检查与恢复

• system_health
• system_permission_guide
• system_get_settings_snapshot
• system_get_focus_status
• system_get_context_snapshot
• system_read_preference_domain

助手级控制界面

启动时的系统写入操作是明确列出的，而非通用操作：

• system_set_appearance_mode
• system_set_show_all_extensions
• system_set_show_hidden_files
• system_set_finder_path_bar
• system_set_finder_status_bar
• system_set_dock_autohide
• system_set_dock_show_recents
• system_set_reduce_motion
• system_set_increase_contrast
• system_set_reduce_transparency

范围受限的 GUI 备用操作包括：

• system_gui_list_menu_bar_items
• system_gui_click_menu_path
• system_gui_press_keys
• system_gui_type_text
• system_gui_click_button
• system_gui_choose_popup_value

GUI 输入允许列表

GUI 输入工具（system_gui_click_menu_path、system_gui_press_keys、system_gui_type_text、system_gui_click_button 和 system_gui_choose_popup_value）只会向你列在 APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS 中的应用发送输入。默认值为空，因此在你设置之前，GUI 输入处于关闭状态。system_gui_list_menu_bar_items 只读取信息，无需允许列表。

• 格式：以逗号分隔的 bundle id，例如 com.apple.TextEdit,com.apple.Safari。逗号周围的大小写和空格均会被忽略。要查找应用的 bundle id，请运行 osascript -e 'id of app "TextEdit"'。
• 设置位置：在 MCP 客户端配置中，此服务的 env 块，例如 "APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS": "com.apple.TextEdit,com.apple.Safari"。在 Claude Desktop 中，打开 Settings > Extensions，配置 Apple System，并填写 "Apps that accept GUI input"。之后重启客户端。
• 每次 GUI 输入调用都必须通过 application 或 bundle_id 指定目标。输入绝不会发送到当前恰好处于最前台的应用；目标应用会先被置于最前台，如果未能置于最前台，调用就会以 GUI_TARGET_NOT_FRONTMOST 失败。
• 即使终端、脚本编辑器和自动化应用已加入允许列表，也一律会返回 TERMINAL_TARGET_REFUSED，因为在其中输入的文本可能会运行代码。此规则涵盖 Terminal、iTerm2、Ghostty、Warp、kitty、WezTerm 等类似终端，以及 Script Editor、Automator、Shortcuts、Xcode、VS Code、Cursor、Windsurf、Zed、JetBrains IDE、BBEdit、Raycast 和 Alfred。
• 调用列表外的应用会返回 GUI_TARGET_NOT_ALLOWED，其 suggestion 会给出需要添加的准确值。

启动清单

• 将 uvx apple-system-mcp（或克隆仓库中的 AppleSystem-MCP/start.sh）添加到 MCP 客户端
• 重新加载或重新连接客户端，使 System 工具界面加载到上下文中
• 首先调用 system_health
• 如果受范围限制的系统操作被阻止，请调用 system_permission_guide
• 调用 system_status，验证完整的上下文界面是否可用

偏好设置域读取接受命名域，例如 com.apple.finder 和 NSGlobalDomain，而不接受文件系统路径或命令选项。-g 和 -globalDomain 别名用于选择 NSGlobalDomain。