macOS控制工具集

MCP macOS控制

Swift内置的本地macOS MCP（模型上下文协议）服务器，提供 74工具 用于全面的计算机控制——鼠标、键盘、屏幕捕获、OCR、窗口管理、视觉分析、CoreML智能、可访问性树读取、通过AXObserver的事件驱动UI等待、通过NSWorkspace的应用程序生命周期事件等待，以及 iPhone镜像自动化 通过macOS Sequoia。

概述

MCP macOS Control使AI代理能够感知macOS应用程序并与之交互，并通过iPhone镜像在连接的iPhone上感知iOS应用程序。所有处理都在使用本机Apple框架的设备上进行。

关键能力：

• 通过CoreGraphics事件实现完全的鼠标和键盘自动化
• 带有OCR文本提取的屏幕截图（Vision框架）
• 带归一化坐标的iPhone镜像控制（macOS 15+）
• 通过AXUIElement API读取辅助功能树
• 设备上CoreML LLM推理（零云令牌）
• 实时屏幕监控，可连续捕获
• 多显示器支持
• 速率限制、结构化日志记录和CI/CD

需求

• macOS 13.0（Ventura）或更高版本（适用于iPhone镜像的macOS 15）
• 苹果硅或英特尔Mac（推荐苹果硅）
• Swift 5.9+/Xcode 16+
• MCP SDK 0.12.0+

安装

git clone https://github.com/aerocristobal/MCP-MacOSControl.git
cd MCP-MacOSControl
swift build -c release

可执行文件位于 .build/release/mcp-macos-control.

Claude桌面配置

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "macos-control": {
      "command": "/path/to/MCP-MacOSControl/.build/release/mcp-macos-control"
    }
  }
}

权限

macOS需要明确的权限：

1. 无障碍 （系统设置>隐私和安全>辅助功能）--鼠标、键盘、窗口激活和辅助功能树都需要
2. 屏幕录制 （系统设置>隐私和安全>屏幕录制）-截图、OCR和连续捕获所需

看 docs/PERMISSIONS.md 详细设置。

安全

威胁模型、AppleScript denylist、审计记录模式和NIST SP 800-53控制映射已上线 docs/SECURITY.md.漏洞应通过私人GitHub安全咨询报告——见该文档第6节。

协作工具调用取消（STORY-027）。 服务器向MCP致敬 notifications/cancelled 消息。五个长时间运行的工具将取消传播到其资源拆卸路径-- wait_for_ui_event （AXObserver注销）， wait_for_element_state （轮询循环在一个周期内退出）， wait_for_app_event （NSWorkspace观察者移除）， smart_interact （在层中止、层跳过之间），以及 run_applescript （osascript SIGTERM，1000毫秒后SIGKILL升级）。SIGTERM到服务器通过相同的路径消耗每个正在进行的呼叫。看 文件/证券.md§5 对于整张桌子。

供应链控制（STORY-021，见§8）。 每次推拉请求：

• 生成一个CycloneDX 1.5+SBOM（通过Syft），覆盖每个可传递的Swift包。
• 运行Grype SBOM扫描+GitHub对SBOM的原生依赖性审查。
• 基于CVSS≥9.0（关键）的发现失败；CVSS 7.0–8.9（高）通过PR评论发出警告，但未被屏蔽。
• 执行许可证允许列表：MIT、Apache-2.0、BSD-2条款、BSD-3条款、ISC。

标记的发布将SBOM（以及VEX文档，如果存在声明）作为证据工件附加到GitHub发布中。Dependabot每月打开Swift包，每周在GitHub Actions上针对同一关卡升级PR。政策在 .github/sbom-policy.yml.

合规性工件

下游SSP作者、评估员和持续监控消费者的机器可读合规状态。所有三个工件都在中进行了版本控制 oscal/ 并在每次推送时根据NIST OSCAL模式进行验证。

漂移之间 docs/SECURITY.md OSCAL伪影通过以下方式双向执行 swift run oscal-drift check --CI在以下任何一项上失败：没有OSCAL的§7/§8控制索赔 implemented-requirement，一个OSCAL implemented-requirement §7/§8未提及，§4接受的风险声明没有匹配的开放式POA&M项目 security-md-section 不再存在。

工具（共75个，16个模块）

鼠标控制（鼠标模块——9个工具）

键盘控制（键盘模块——4个工具）

屏幕捕获和OCR（屏幕捕获模块——2个工具）

窗口管理（WindowModule-2个工具）

连续捕获（连续捕获模块——6个工具）

视觉分析（视觉模块——5个工具）

CoreML智能（CoreMLModule——8个工具）

实时分析（实时模块——4个工具）

系统（系统模块——3个工具）

可访问性（可访问性模块-5个工具）

返回结构化JSON，其中包含每个UI元素的角色、标题、值、位置、大小和子元素。可配置的 max_depth （默认值6）。注意：仅适用于macOS应用程序——iPhone镜像内容需要 iphone_screenshot_with_ocr.

事件驱动等待（WaitForUIEventModule-1工具）

用精确的事件驱动同步取代固定的睡眠和屏幕截图轮询循环。支持的通知： AXWindowCreated, AXUIElementDestroyed, AXFocusedUIElementChanged, AXValueChanged, AXSelectedTextChanged, AXTitleChanged, AXMainWindowChanged, AXFocusedWindowChanged.同一电话上有多个并发呼叫 (application, notification) 配对共享一个基础 AXObserver默认超时30秒，硬上限300秒。请参阅 ax_observer_notifications MCP提示路由指引。

元素状态轮询（WaitForElementStateModule-1工具）

有记录的回退到 wait_for_ui_event 对于没有 AXObserver 通知（按钮启用，微调器消失，行被选中）。条件语法为 "<field> = <value>".Boolean字段： enabled, exists, focused, selected, expanded, visible_in_viewport, is_main, is_minimized, is_frontmost （例如。 enabled = true, exists = false).字符串字段： value （精确、区分大小写、引用——例如。 value = 'Connected').固定100ms轮询节奏（用覆盖 MCP_MACOS_CONTROL_POLL_INTERVAL_MS).默认超时30秒，硬上限120秒——更适合长时间事件驱动的等待 wait_for_ui_event.

应用程序生命周期事件（WaitForAppEventModule-1工具）

事件驱动的排序方式“打开应用程序”→ 应用程序已准备就绪→ “交互”工作流。与 wait_for_ui_event （AXObserver，需要一个已经运行的AX可查询目标），这是预启动功能，不需要访问权限。支持的活动： launched, activated, terminated, deactivated, hidden, unhidden.可选 bundle_identifier （反向DNS，例如。 com.apple.TextEdit)过滤到一个应用程序；省略它以解决任何应用程序中的下一个匹配事件。仅解决 下一个 过渡，而非现状。同一设备上有多个并发呼叫 (event, bundle_identifier) 共享一个潜在的观察者。默认超时30秒，硬上限300秒。请参阅 interaction_hierarchy MCP提示何时更喜欢它 wait_for_ui_event.

交互路由器（SmartInteractionModule-1工具）-- 建议用于AI代理

UI交互的推荐入口点。 而不是在两者之间做出选择 click_element, run_applescript, element_at_position，以及 click_screen 你自己，陈述你的 意图 并让路由器选择最可靠的可用层。它查询每个应用程序的功能注册表，跳过目标应用程序已知失败的层，并返回 decision_log 记录每一层尝试、跳过或失败的情况（并说明原因），以及 interaction_method 和 confidence当耗尽时，它返回结构化错误 all_layers_failed 带有重试建议。路由器只知道动作 派遣，而不是其效果——在采取行动后进行验证 wait_for_ui_event / wait_for_element_state。请参阅 interaction_hierarchy MCP提示。

iPhone镜像（iPhone镜像模块——21个工具）

需要配置了iPhone镜像的macOS 15（Sequoia）。所有坐标都使用相对于iPhone屏幕内容区域的归一化0.0-1.0范围。

iPhone镜像的工作原理： 服务器检测iPhone镜像窗口，通过视觉矩形检测校准iPhone屏幕内容区域，并将归一化坐标转换为绝对屏幕坐标。滑动手势使用轻松输入输出，轻轻一推即可确保iOS手势识别。文本输入使用剪贴板粘贴来支持通用语言。

环境变量

看 docs/AUDIT-LOG-OPERATIONS.md 对于完整 审计子系统操作员指南（链验证、保留、事件 响应、接收器特定配置）。

每个应用程序的功能覆盖

服务器附带了每个应用程序交互层功能的注册表 (ax_supported, applescript_supported, hit_test_supported)所以智能路由 可以跳过给定应用程序的已知故障层（例如，无法使用的Electron应用程序 可达性树）。已发货的默认值存在于包捆绑包中 (Sources/MacOSControlLib/Router/Defaults/default-app-capabilities.json, ~27 众所周知的应用程序），并通过MCP资源以只读方式公开 mcp://capability-registry/contents （JSON： schema_version + entries[]，每 携带a source 的 defaults 或 user_override).

高级用户可以在不重建的情况下对单个条目进行阴影处理。创建：

~/Library/Application Support/mcp-macos-control/app-overrides.json

（或点 MCP_MACOS_CONTROL_OVERRIDES_PATH 在任何路径上）使用相同的模式：

{
  "schema_version": 1,
  "entries": [
    { "bundle_id": "com.example.app", "ax_supported": true,
      "applescript_supported": false, "hit_test_supported": true }
  ]
}

超控加载为 软故障：跳过格式错误的覆盖文件（ 服务器记录结构化 invalid_capability_registry_override 错误并启动 通常使用出厂默认值）。未知的JSON字段被忽略，因此 模式向前兼容。覆盖更改在服务器重新启动时生效 （无热重新加载）。STORY-020使捆绑的默认文件保持最新状态 兼容性目录工作。

建筑

Sources/
  MacOSControlLib/                   # Library target
    ToolModule.swift                 # ToolModule protocol
    ToolRouter.swift                 # Module registry + dispatch
    Errors.swift                     # MCPError structured errors
    Logger.swift                     # Structured logging
    RateLimiter.swift                # Token bucket rate limiter
    MouseControl.swift               # CGEvent mouse automation
    KeyboardControl.swift            # CGEvent keyboard automation
    ScreenCapture.swift              # Screenshot capture
    OCRProcessor.swift               # Vision OCR
    WindowManagement.swift           # Window list/activate
    VisionAnalyzer.swift             # Vision framework analysis
    CoreMLManager.swift              # CoreML model management
    ContinuousCaptureManager.swift   # ScreenCaptureKit streams
    RealtimeAnalyzer.swift           # Continuous vision analysis
    Accessibility/
      AccessibilityTreeBuilder.swift # AXUIElement tree traversal
      AXNodeSerializer.swift         # JSON shaping + schema_version
      AXNode.swift                   # Tree value type
    IPhoneMirroring/
      MirroringWindowDetector.swift  # Window detection + focus guard
      CoordinateTranslator.swift     # Content rect calibration + coord translation
      GestureEngine.swift            # Tap, swipe, scroll gestures
      IOSNavigation.swift            # Home, Spotlight, App Switcher, open app
      IPhoneTextInput.swift          # Clipboard paste, key events
    Modules/
      MouseModule.swift              # 9 mouse tools
      KeyboardModule.swift           # 4 keyboard tools
      ScreenCaptureModule.swift      # 2 capture tools
      WindowModule.swift             # 2 window tools
      ContinuousCaptureModule.swift  # 6 continuous capture tools
      VisionModule.swift             # 5 vision tools
      CoreMLModule.swift             # 8 CoreML tools
      RealtimeModule.swift           # 4 realtime tools
      SystemModule.swift             # 3 system tools
      AccessibilityModule.swift      # 1 accessibility tool
      IPhoneMirroringModule.swift    # 21 iPhone tools
  MCP-MacOSControl/
    Server.swift                     # Entry point (33 lines)
Tests/
  MCP-MacOSControlTests/            # 178 unit tests

发展

swift build           # Debug build
swift build -c release # Release build
swift test            # Run the unit suite (integration suite auto-skips)

CI通过GitHub Actions（macOS 15，构建+测试）在每次推送时运行。

集成套件（STORY-012）

一个单独的、可选择的端到端套件(MCP-MacOSControlIntegrationTests) 执行完整的代理工作流程 真实的 macOS应用程序通过真实 ToolRouter --打开/键入/保存、NSWorkspace启动流程、， smart_interact 路由+回退，协调工具向后兼容性，结构化错误 在每个注册代码中签订合同，并进行iPhone镜像烟雾测试。它 需要登录的GUI会话和辅助功能权限，因此它是封闭的 后面 CI_MACOS_INTEGRATION 并在merge上运行 main +每晚，不是 per-PR。如果没有标记，每个场景都会跳过，所以很简单 swift test 停留 绿色。

# Grant Accessibility to the process running swift test first, then:
CI_MACOS_INTEGRATION=true swift test --filter MCP_MacOSControlIntegrationTests

看 集成CI设置 和 贡献.md.

文档

• 快速入门指南
• 权限指南
• 测试检查表
• 集成CI设置
• CoreML集成
• 产品需求
• 应用程序兼容性目录 --从集成测试观察中重新生成的循证目录（STORY-020）

许可证

MIT许可证

致谢

• 与 模型上下文协议 Swift SDK
• 使用苹果的原生框架（CoreGraphics、Vision、CoreML、ScreenCaptureKit、AppKit）