MCP Macoscontrol

MCP macOS控制

Swift内置的本地macOS MCP（模型上下文协议）服务器，提供 65工具 用于全面的计算机控制——鼠标、键盘、屏幕捕获、OCR、窗口管理、视觉分析、CoreML智能、可访问性树读取，以及 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 详细设置。

工具（共65个，11个模块）

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

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

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

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

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

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

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

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

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

无障碍（无障碍模块-1个工具）

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

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

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

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

环境变量

建筑

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 178 unit tests

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

文档

• 快速入门指南
• 权限指南
• 测试检查表
• CoreML集成
• 产品需求

许可证

MIT许可证

致谢

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