Macos Ui Automation Mcp

🚀 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. 验证是否出现成功消息"

📚 详细文档

可用工具

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！😄