金大哥 - macos-ui-automation-mcp MCP 详情

article

README

🚀 macOS版Playwright MCP 🎭

这是一款适用于原生macOS应用程序的工具，就像Playwright用于浏览器一样强大。它能让Claude通过自然语言控制任何Mac应用程序，是在AI辅助下进行Mac应用程序开发和测试的完美选择。

🚀 快速开始

1. 安装

git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync

2. 设置辅助功能权限

⚠️ 重要提示

必须为父应用程序启用辅助功能：

如果使用终端：将终端添加到系统设置 → 隐私与安全性 → 辅助功能中。

如果使用VS Code：将VS Code添加到系统设置 → 隐私与安全性 → 辅助功能中。

如果使用Claude Code：将Claude Code添加到系统设置 → 隐私与安全性 → 辅助功能中。

父应用程序需要此权限，因为它是实际执行MCP服务器的程序。

3. 配置Claude Code

在Claude Code MCP设置中添加以下内容：

{
  "mcpServers": {
    "macos-ui-automation": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/macos-ui-automation-mcp",
        "run",
        "macos-ui-automation-mcp"
      ]
    }
  }
}

4. 开始自动化操作！

现在你可以向Claude提出以下请求：

"查找计算器应用程序中的所有按钮"
"点击我应用程序中的提交按钮"
"点击截图按钮以捕获当前窗口"
"通过填写凭证并点击提交来测试登录流程"

✨ 主要特性

这是一个MCP（模型上下文协议）服务器，它赋予Claude查看和与任何macOS应用程序交互的能力。就像Playwright用于浏览器一样，它适用于原生Mac应用程序。

适用场景：

🧪 测试Mac应用程序 - "测试我应用程序中的登录流程"
🔍 应用程序开发 - "检查所有按钮是否正确标注"
🤖 UI自动化 - "填写此表单并提交"
📱 应用程序探索 - "向我展示访达中的所有交互式元素"

📦 安装指南

git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync

💻 使用示例

基础用法

# 所有应用程序中的所有按钮
$..[?(@.role=='AXButton')]

# 具有特定文本的按钮
$..[?(@.title=='Submit')]

# 所有启用的文本字段
$..[?(@.role=='AXTextField' && @.enabled==true)]

# 具有辅助功能标识符的元素
$..[?(@.ax_identifier=='loginButton')]

# 特定应用程序中的元素
$.processes[?(@.name=='Calculator')]..[?(@.role=='AXButton')]

高级用法

"测试我的登录流程：
1. 找到用户名字段并输入 'testuser'
2. 找到密码字段并输入 'password123'
3. 点击登录按钮
4. 验证是否出现成功消息"

📚 详细文档

可用工具

| 属性 | 详情 | |------|------| | find_elements | 使用JSONPath查找UI元素 | | find_elements_in_app | 在特定应用程序中搜索 | | click_by_accessibility_id | 使用辅助功能操作进行点击 | | click_at_position | 在屏幕坐标处点击 | | type_text_to_element_by_selector | 向元素中输入文本 | | get_app_overview | 获取正在运行的应用程序的概述 | | list_running_applications | 列出所有正在运行的应用程序 | | check_accessibility_permissions | 验证设置是否正确 |

JSONPath示例

使用强大的JSONPath查询查找元素：

# 所有应用程序中的所有按钮
$..[?(@.role=='AXButton')]

# 具有特定文本的按钮
$..[?(@.title=='Submit')]

# 所有启用的文本字段
$..[?(@.role=='AXTextField' && @.enabled==true)]

# 具有辅助功能标识符的元素
$..[?(@.ax_identifier=='loginButton')]

# 特定应用程序中的元素
$.processes[?(@.name=='Calculator')]..[?(@.role=='AXButton')]

应用程序测试

此工具在开发和测试Mac应用程序时表现出色：

测试自动化

"测试我的登录流程：
1. 找到用户名字段并输入 'testuser'
2. 找到密码字段并输入 'password123'
3. 点击登录按钮
4. 验证是否出现成功消息"

UI验证

"检查我的设置窗口：
- 所有按钮是否正确标注？
- 是否有任何没有辅助功能标识符的文本字段？
- 点击截图按钮以捕获当前状态"

辅助功能审核

"对我的应用程序进行辅助功能审核：
- 查找所有没有辅助功能标签的交互式元素
- 检查键盘导航是否正常工作
- 识别任何可能难以使用的元素"

添加截图功能

我们没有提供内置的截图功能，但你可以轻松地将其添加到你的Mac应用程序中！查看我们基于实际应用程序的完整Swift实现示例。

关键点：

使用ScreenCaptureKit（macOS 14+）进行高质量捕获
自动找到你的应用程序窗口
将带时间戳的截图保存到“文档/截图”文件夹中
与这个MCP完美集成 - 只需添加一个辅助功能标识符！

与Playwright MCP一起使用：

"点击截图按钮以捕获当前窗口"

MCP将通过辅助功能ID找到你的按钮并触发截图！

开发设置

对于贡献者和高级用户：

# 克隆并安装
git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync --dev

# 运行测试
uv run python -m pytest tests/ -v

# 检查代码质量
uv run ruff check src/ tests/ mcp_server_wrapper.py
uv run ruff format

# 测试MCP服务器
uv run macos-ui-automation-mcp

🔧 技术细节

架构

基于以下技术构建：

FastMCP - MCP服务器框架
PyObjC - macOS辅助功能API绑定
Pydantic - 类型安全的数据模型
JSONPath - 强大的元素查询
全面的测试套件 - 用于在不使用真实UI的情况下进行测试的模拟系统

📄 许可证

本项目采用MIT许可证，你可以在你的项目中自由使用！

⚠️ 重要提示

辅助功能权限

必须授予父应用程序（终端、VS Code等）
而不是Python或MCP服务器本身
这是在macOS上进行任何UI自动化所必需的

截图权限

如果你的应用程序具有截图功能，它需要屏幕录制权限
将你的应用程序添加到系统设置 → 隐私与安全性 → 屏幕录制中
这与辅助功能权限是分开的

性能提示

尽可能使用特定应用程序的搜索（find_elements_in_app）
浅层搜索在获取概述时更快
深层搜索更全面但速度较慢

局限性

需要辅助功能API访问权限（某些应用程序可能会限制此权限）
最适合原生macOS应用程序
某些系统级元素可能无法访问

🎭 为什么叫“Mac版Playwright”？

就像Playwright通过提供简单的API来控制浏览器，彻底改变了Web测试一样，这个工具也为原生macOS应用程序做了同样的事情。你无需编写复杂的GUI自动化脚本，只需用自然语言告诉Claude你想要测试或自动化的内容。

它非常适合AI辅助开发的时代！🤖

需要帮助？ 查看示例文件夹或提出问题。更好的是，提交一个PR！😄

macos-ui-automation-mcp