Macos Ui MCP

macOS UI MCP服务器

模型上下文协议（MCP）服务器，通过Accessibility API为人工智能代理提供本机macOS UI自动化功能。

作者：安东·斯塔里科夫 许可证: EUPL-1.2

特性

• 元素发现：导航和检查UI元素层次结构
• UI操作：单击、键入、设置值并执行辅助功能操作
• 高级鼠标：滚动、右键单击、双击、悬停、拖放
• 菜单导航：导航菜单路径并获取菜单结构
• 剪贴板操作：将文本和图像读/写到剪贴板
• 窗口管理：获取/设置窗口边界、最小化、还原、提升
• 文本选择：选择文本范围，获取所选文本
• 元件检查：获取所有属性，突出显示元素，捕获元素
• 文件对话窗口：导航、选择文件、设置文件名、确认/取消
• 应用程序管理：启动、激活和退出应用程序
• 元素观察：等待元素并监视状态变化
• 键盘输入：键入文本并发送键盘快捷键
• 截图：捕获窗口、区域或整个屏幕
• 权限检查：验证访问权限

需求

• macOS 26.0或更高版本
• Swift 6.0+
• 在系统设置中授予的可访问性权限

建筑

# Debug build
make build

# Release build (universal binary: ARM64 + x86_64)
make release

# Run tests (non-parallel to avoid UI conflicts)
make test

# Run the server
make run

# Install to /usr/local/bin
make install

# Show all available commands
make help

通用发布二进制文件将位于 .build/universal/macos-ui-mcp.

授予无障碍权限

1. 打开 系统设置 > 隐私和安全 > 无障碍
2. 点击 + 按钮
3. 导航到构建的二进制文件或终端应用程序
4. 启用切换

MCP配置

添加到您的Claude Code MCP配置中(~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "macos-ui": {
      "command": "/path/to/macos-ui-mcp"
    }
  }
}

可用工具

元素发现

UI操作

应用程序管理

元素观察

键盘输入

截图

权限

高级鼠标交互

菜单导航

剪贴板操作

窗口管理

文本选择

元件检查

文件对话框处理

示例用法

计算器自动化

1. Launch Calculator:
   launch_application(bundle_id: "com.apple.calculator")

2. Type a calculation:
   type_text(bundle_id: "com.apple.calculator", text: "7+3")

3. Press equals:
   send_shortcut(bundle_id: "com.apple.calculator", key: "return", modifiers: [])

4. Get the result:
   get_element_tree(bundle_id: "com.apple.calculator", max_depth: 5)

5. Capture the result:
   capture_window(bundle_id: "com.apple.calculator")

查找和单击元素

1. Find a button:
   find_elements(bundle_id: "com.apple.calculator", role: "AXButton", title: "5")

2. Click using the returned path:
   click(bundle_id: "com.apple.calculator", path: {...})

菜单导航

1. Open a menu item:
   navigate_menu(bundle_id: "com.apple.TextEdit", menu_path: "File > Save As...")

2. Get all menu items:
   get_menu_structure(bundle_id: "com.apple.TextEdit")

文件对话框工作流

1. Navigate to Save As dialog:
   navigate_menu(bundle_id: "com.apple.TextEdit", menu_path: "File > Save As...")

2. Navigate to Desktop:
   navigate_dialog(bundle_id: "com.apple.TextEdit", path: "~/Desktop")

3. Set filename:
   set_filename(bundle_id: "com.apple.TextEdit", filename: "mydocument.txt")

4. Save:
   confirm_dialog(bundle_id: "com.apple.TextEdit")

窗口管理

1. List all windows:
   list_windows(bundle_id: "com.apple.finder")

2. Move and resize:
   set_window_bounds(bundle_id: "com.apple.finder", x: 100, y: 100, width: 800, height: 600)

3. Minimize:
   minimize_window(bundle_id: "com.apple.finder")

剪贴板操作

1. Copy text to clipboard:
   write_clipboard(text: "Hello, World!")

2. Read clipboard:
   read_clipboard()

元素路径

元素使用描述其在UI层次结构中位置的路径进行标识：

{
  "segments": [
    {"role": "AXApplication", "title": "Calculator"},
    {"role": "AXWindow", "title": "Calculator"},
    {"role": "AXButton", "identifier": "Five"}
  ]
}

每个分段可以通过以下方式匹配：

• role：辅助功能角色（AXButton、AXTextField等）
• title：元素标题
• identifier：可访问性标识符
• index：兄弟姐妹之间的位置

错误代码

建筑

Sources/MacOSUIMCP/
├── main.swift              # Entry point
├── Server/
│   ├── MCPServer.swift     # JSON-RPC message handling
│   ├── StdioTransport.swift
│   └── Logger.swift
├── Tools/
│   ├── ElementTools.swift
│   ├── ActionTools.swift
│   ├── ApplicationTools.swift
│   ├── ObservationTools.swift
│   ├── KeyboardTools.swift
│   ├── ScreenshotTools.swift
│   ├── PermissionTools.swift
│   ├── MouseTools.swift        # scroll, right_click, double_click, hover, drag_drop
│   ├── MenuTools.swift         # navigate_menu, get_menu_structure
│   ├── ClipboardTools.swift    # read_clipboard, write_clipboard
│   ├── WindowTools.swift       # get/set_window_bounds, list_windows, minimize, restore, raise
│   ├── TextSelectionTools.swift # select_text_range, get_selected_text, select_all
│   ├── InspectionTools.swift   # get_all_attributes, highlight_element, capture_element
│   └── FileDialogTools.swift   # navigate_dialog, select_file, set_filename, confirm, cancel
├── Accessibility/
│   ├── AXElement.swift
│   ├── AXApplication.swift
│   ├── AXMenu.swift            # Menu traversal
│   └── ElementPathResolver.swift
├── Input/
│   ├── KeyboardSimulator.swift
│   └── MouseSimulator.swift    # Mouse event simulation
├── Screenshot/
│   └── ScreenCapture.swift
├── Clipboard/
│   └── ClipboardManager.swift  # NSPasteboard wrapper
├── Window/
│   └── WindowManager.swift     # Window AX operations
├── Highlight/
│   └── HighlightOverlay.swift  # Visual highlight overlay
└── Models/
    ├── Application.swift
    ├── Element.swift
    ├── ElementPath.swift
    ├── Errors.swift
    ├── ClipboardContent.swift
    ├── WindowBounds.swift
    ├── WindowInfo.swift
    ├── TextSelectionResult.swift
    ├── AttributeValue.swift
    ├── ElementAttributes.swift
    └── HighlightResult.swift

许可证

版权所有（c）2025安东·斯塔里科夫

根据欧盟公共许可证（EUPL）1.2版许可。 除非遵守许可证，否则您不得使用此作品。

看 许可证 文件以获取完整的许可证文本。