AI导哈

macOS桌面自动化工具

macos-mcp-operator是一个本地MCP（模型上下文协议）服务器，专为macOS 14+设计，优化了单用户自托管工作流，提供桌面自动化功能。

  • by jason5545
  • Swift
  • 本地部署
  • 更新于
在 GitHub 查看 jason5545/macos-mcp-operator

使用说明

macos-mcp操作程序v1.1

适用于macOS 14+桌面自动化的本地MCP（模型上下文协议）服务器，针对单用户自主机工作流进行了优化。

v1.1中发生了什么变化

  • 批准/令牌流已禁用(risk_class 和 confirmation_token 为了兼容性而忽略）。
  • AppleScript的执行现在通过本地代理主机进程进行(macos-mcp-operator-host)通过Unix套接字。
  • 添加了权限工具：
    • permissions_status
    • permissions_probe_automation
    • permissions_open_settings
  • set_safety_mode 和 update_app_whitelist 作为已弃用的no-op工具保持可用。

构建

swift build -c release

二进制路径：

.build/release/macos-mcp-operator
.build/release/macos-mcp-operator-host

权限

向主机应用程序/进程授予权限：

  • 可访问性（鼠标/键盘控制）
  • 屏幕录制(screen_capture)
  • 自动化（苹果活动，特定于目标应用程序）

如果缺少权限，工具调用将返回显式错误代码/消息，例如：

  • ACCESSIBILITY_MISSING
  • SCREEN_RECORDING_MISSING
  • AUTOMATION_NOT_ALLOWED
  • BROKER_UNAVAILABLE

配置

路径：

~/.config/macos-mcp-operator/config.json

v1.1默认形状：

{
  "default_mode": "restricted",
  "app_whitelist": [
    "com.apple.Notes"
  ],
  "sensitive_bundle_ids": [
    "com.apple.systempreferences"
  ],
  "dangerous_key_chords": [
    ["cmd", "q"],
    ["cmd", "w"],
    ["cmd", "delete"]
  ],
  "audit_enabled": true,
  "kill_switch_hotkey": "ctrl+opt+cmd+.",
  "approval_enabled": false,
  "execution_backend": "broker",
  "broker": {
    "bundle_id": "com.jianruicheng.macos-mcp-operator.host",
    "app_path": "~/Applications/macos-mcp-operator-host.app",
    "socket_path": "~/.local/share/macos-mcp-operator/broker.sock",
    "launch_agent_label": "com.jianruicheng.macos-mcp-operator.host"
  }
}

审核日志路径：

~/Library/Logs/macos-mcp-operator/audit.jsonl

工具

  1. set_safety_mode （不推荐使用op）
  2. update_app_whitelist （不推荐使用op）
  3. list_windows
  4. focus_window
  5. mouse_move
  6. mouse_click
  7. mouse_drag
  8. mouse_scroll
  9. text_input
  10. key_chord
  11. screen_capture
  12. app_launch
  13. app_open_url
  14. app_open_path
  15. app_quit
  16. applescript_run （经纪人支持）
  17. applescript_app_command （经纪人支持）
  18. permissions_status
  19. permissions_probe_automation
  20. permissions_open_settings
  21. automation_stop

聚焦行为和目标控制

输入工具现在可以针对特定的应用程序/窗口，而无需始终强制前台切换。

  • focus_window
    • 新的可选标志： activate_all_windows （默认值： false)
    • 集 true 使用激活目标应用程序所有窗口的传统行为。
  • mouse_click, mouse_drag, mouse_scroll, text_input, key_chord
    • 新的可选字段：
      • bundle_id
      • window_id
      • auto_focus （默认值： false)
      • launch_if_needed （默认值： false)
    • 行为：
      • 如果没有提供目标，则命令将应用于当前最前端的应用程序（传统行为）。
      • 如果提供了目标，但不是最前面的：
        • auto_focus=false ->退货 TARGET_NOT_FRONTMOST.
        • auto_focus=true ->先聚焦目标，然后执行。

例子：

{
  "name": "text_input",
  "arguments": {
    "text": "hello",
    "bundle_id": "com.apple.Notes",
    "auto_focus": true
  }
}

脚本

  • scripts/package-host-app.sh
    • 构建和打包 ~/Applications/macos-mcp-operator-host.app
    • 安装/启动LaunchAgent： com.jianruicheng.macos-mcp-operator.host
  • scripts/sign-host-app.sh
    • 签署主机应用程序
    • 自动检测团队ID(MW4GWYGX56)并尽可能匹配身份
  • scripts/install-claude-mcp.sh
    • 更新：
      • ~/Library/Application Support/Claude/claude_desktop_config.json
      • ~/.claude.json
    • 与验证 claude mcp get macos-mcp-operator

建议的安装顺序

./scripts/package-host-app.sh
./scripts/sign-host-app.sh
./scripts/install-claude-mcp.sh

权限恢复手册

快速打开设置页面：

  • 可访问性：
    • open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
  • 屏幕录制：
    • open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
  • 自动化：
    • open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"

如果需要，重置TCC条目（您需要重新授予）：

tccutil reset Accessibility com.jianruicheng.macos-mcp-operator.host
tccutil reset ScreenCapture com.jianruicheng.macos-mcp-operator.host
tccutil reset AppleEvents com.jianruicheng.macos-mcp-operator.host

MCP协议版本

支持的协议版本（从最新到最旧）：

  • 2025-11-25
  • 2025-06-18
  • 2025-03-26

相关 MCP