# Playwright MCP for macOS 🎭
**Like Playwright, but for native macOS applications. Control any Mac app with natural language through Claude - perfect for developing and testing Mac applications with AI assistance.**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
## 🎯 What is this?
This is an MCP (Model Context Protocol) server that gives Claude the ability to see and interact with any macOS application - just like Playwright does for web browsers, but for native Mac apps.
**Perfect for:**
- 🧪 **Testing Mac applications** - "Test the login flow in my app"
- 🔍 **App development** - "Check if all buttons are properly labeled"
- 🤖 **UI automation** - "Fill out this form and submit it"
- 📱 **App exploration** - "Show me all the interactive elements in Finder"
## 🚀 Quick Start
### 1. Install
```bash
git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync
```
### 2. Set Up Accessibility Permissions
⚠️ **Critical**: Enable accessibility for your **parent application**:
- **If using Terminal**: Add Terminal to `System Settings → Privacy & Security → Accessibility`
- **If using VS Code**: Add VS Code to `System Settings → Privacy & Security → Accessibility`
- **If using Claude Code**: Add Claude Code to `System Settings → Privacy & Security → Accessibility`
*The parent app needs permission because it's the one actually executing the MCP server.*
### 3. Configure Claude Code
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"macos-ui-automation": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/macos-ui-automation-mcp",
"run",
"macos-ui-automation-mcp"
]
}
}
}
```
### 4. Start Automating!
Now you can ask Claude things like:
- *"Find all buttons in the Calculator app"*
- *"Click the submit button in my app"*
- *"Click the screenshot button to capture the current window"*
- *"Test the login flow by filling in credentials and clicking submit"*
## 🛠 Available Tools
| Tool | Description | Use Case |
|------|-------------|----------|
| `find_elements` | Find UI elements using JSONPath | "Show me all text fields" |
| `find_elements_in_app` | Search within a specific app | "Find buttons in Safari" |
| `click_by_accessibility_id` | Click using accessibility actions | "Click the submit button" |
| `click_at_position` | Click at screen coordinates | "Click at position (100, 200)" |
| `type_text_to_element_by_selector` | Type text into elements | "Type 'hello' into the search field" |
| `get_app_overview` | Overview of running applications | "What apps are currently running?" |
| `list_running_applications` | List all running apps | "Show me all open applications" |
| `check_accessibility_permissions` | Verify setup is correct | "Is accessibility properly configured?" |
## 🔍 JSONPath Examples
Find elements using powerful JSONPath queries:
```bash
# All buttons in any app
$..[?(@.role=='AXButton')]
# Buttons with specific text
$..[?(@.title=='Submit')]
# All text fields that are enabled
$..[?(@.role=='AXTextField' && @.enabled==true)]
# Elements with accessibility identifiers
$..[?(@.ax_identifier=='loginButton')]
# Elements in a specific app
$.processes[?(@.name=='Calculator')]..[?(@.role=='AXButton')]
```
## 🧪 Perfect for App Testing
This tool shines when developing and testing Mac applications:
### Test Automation
```
"Test my login flow:
1. Find the username field and type 'testuser'
2. Find the password field and type 'password123'
3. Click the login button
4. Verify a success message appears"
```
### UI Validation
```
"Check my settings window:
- Are all buttons properly labeled?
- Are there any text fields without accessibility identifiers?
- Click the screenshot button to capture the current state"
```
### Accessibility Auditing
```
"Audit my app for accessibility:
- Find all interactive elements without accessibility labels
- Check if keyboard navigation works properly
- Identify any elements that might be hard to use"
```
## 📸 Adding Screenshots to Your App
We don't provide built-in screenshot functionality, but you can easily add it to your Mac app! Check out our [complete Swift implementation example](examples/screenshot.swift) based on a real-world app.
**Key points:**
- Uses `ScreenCaptureKit` (macOS 14+) for high-quality captures
- Automatically finds your app window
- Saves timestamped screenshots to Documents/Screenshots
- Integrates perfectly with this MCP - just add an accessibility identifier!
**Usage with Playwright MCP:**
```
"Click the screenshot button to capture the current window"
```
The MCP will find your button by accessibility ID and trigger the screenshot!
## 📦 Development Setup
For contributors and advanced users:
```bash
# Clone and install
git clone https://github.com/mb-dev/macos-ui-automation-mcp.git
cd macos-ui-automation-mcp
uv sync --dev
# Run tests
uv run python -m pytest tests/ -v
# Check code quality
uv run ruff check src/ tests/ mcp_server_wrapper.py
uv run ruff format
# Test the MCP server
uv run macos-ui-automation-mcp
```
## 🤝 Contributing & Bug Reports
I have limited time to fix issues, so here's the deal:
- 🐛 **Found a bug?** File an issue, but please include:
- Your macOS version
- Steps to reproduce
- What you expected vs what happened
- 🛠 **Want it fixed faster?** The best way is to:
1. Fork the repo
2. Write a failing test that reproduces the bug
3. Fix the bug
4. Submit a PR
- ✨ **Want a feature?** Same deal - code it up and submit a PR!
I'm happy to review PRs and provide guidance, but I can't promise quick fixes for reported issues. The codebase is well-tested and documented, so dive in! 🚀
## 🔧 Architecture
Built with:
- **FastMCP** - MCP server framework
- **PyObjC** - macOS accessibility API bindings
- **Pydantic** - Type-safe data models
- **JSONPath** - Powerful element querying
- **Comprehensive test suite** - Fake system for testing without real UI
## ⚠️ Important Notes
### Accessibility Permissions
- Must be granted to the **parent application** (Terminal, VS Code, etc.)
- Not to Python or the MCP server itself
- Required for any UI automation on macOS
### Screenshot Permissions
- If your app has screenshot functionality, it needs **Screen Recording** permission
- Add your app to `System Settings → Privacy & Security → Screen Recording`
- This is separate from accessibility permissions
### Performance Tips
- Use app-specific searches when possible (`find_elements_in_app`)
- Shallow searches are faster for overviews
- Deep searches are thorough but slower
### Limitations
- Requires accessibility API access (some apps restrict this)
- Works best with native macOS applications
- Some system-level elements may not be accessible
## 📄 License
MIT License - feel free to use this in your projects!
## 🎭 Why "Playwright for Mac"?
Just like Playwright revolutionized web testing by providing a simple API to control browsers, this tool does the same for native macOS applications. Instead of writing complex GUI automation scripts, just tell Claude what you want to test or automate in natural language.
Perfect for the age of AI-assisted development! 🤖
---
**Need help?** Check the [examples/](examples/) folder or [open an issue](https://github.com/mb-dev/macos-ui-automation-mcp/issues). Better yet, submit a PR! 😄
Raw data
{
"_id": null,
"home_page": null,
"name": "macos-ui-automation-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "accessibility, automation, claude, jsonpath, macos, mcp, ui",
"author": "mochen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f0/44/6f400bc372b968b0ee190f905481f5f3c7bf0c556448cb25871050c97749/macos_ui_automation_mcp-0.2.0.tar.gz",
"platform": null,
"description": "# Playwright MCP for macOS \ud83c\udfad\n\n**Like Playwright, but for native macOS applications. Control any Mac app with natural language through Claude - perfect for developing and testing Mac applications with AI assistance.**\n\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io/)\n[](https://opensource.org/licenses/MIT)\n\n## \ud83c\udfaf What is this?\n\nThis is an MCP (Model Context Protocol) server that gives Claude the ability to see and interact with any macOS application - just like Playwright does for web browsers, but for native Mac apps.\n\n**Perfect for:**\n- \ud83e\uddea **Testing Mac applications** - \"Test the login flow in my app\"\n- \ud83d\udd0d **App development** - \"Check if all buttons are properly labeled\"\n- \ud83e\udd16 **UI automation** - \"Fill out this form and submit it\"\n- \ud83d\udcf1 **App exploration** - \"Show me all the interactive elements in Finder\"\n\n## \ud83d\ude80 Quick Start\n\n### 1. Install\n```bash\ngit clone https://github.com/mb-dev/macos-ui-automation-mcp.git\ncd macos-ui-automation-mcp\nuv sync\n```\n\n### 2. Set Up Accessibility Permissions\n\u26a0\ufe0f **Critical**: Enable accessibility for your **parent application**:\n\n- **If using Terminal**: Add Terminal to `System Settings \u2192 Privacy & Security \u2192 Accessibility`\n- **If using VS Code**: Add VS Code to `System Settings \u2192 Privacy & Security \u2192 Accessibility` \n- **If using Claude Code**: Add Claude Code to `System Settings \u2192 Privacy & Security \u2192 Accessibility`\n\n*The parent app needs permission because it's the one actually executing the MCP server.*\n\n### 3. Configure Claude Code\nAdd to your Claude Code MCP settings:\n```json\n{\n \"mcpServers\": {\n \"macos-ui-automation\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/absolute/path/to/macos-ui-automation-mcp\",\n \"run\",\n \"macos-ui-automation-mcp\"\n ]\n }\n }\n}\n```\n\n### 4. Start Automating!\nNow you can ask Claude things like:\n- *\"Find all buttons in the Calculator app\"*\n- *\"Click the submit button in my app\"*\n- *\"Click the screenshot button to capture the current window\"* \n- *\"Test the login flow by filling in credentials and clicking submit\"*\n\n## \ud83d\udee0 Available Tools\n\n| Tool | Description | Use Case |\n|------|-------------|----------|\n| `find_elements` | Find UI elements using JSONPath | \"Show me all text fields\" |\n| `find_elements_in_app` | Search within a specific app | \"Find buttons in Safari\" |\n| `click_by_accessibility_id` | Click using accessibility actions | \"Click the submit button\" |\n| `click_at_position` | Click at screen coordinates | \"Click at position (100, 200)\" |\n| `type_text_to_element_by_selector` | Type text into elements | \"Type 'hello' into the search field\" |\n| `get_app_overview` | Overview of running applications | \"What apps are currently running?\" |\n| `list_running_applications` | List all running apps | \"Show me all open applications\" |\n| `check_accessibility_permissions` | Verify setup is correct | \"Is accessibility properly configured?\" |\n\n## \ud83d\udd0d JSONPath Examples\n\nFind elements using powerful JSONPath queries:\n\n```bash\n# All buttons in any app\n$..[?(@.role=='AXButton')]\n\n# Buttons with specific text\n$..[?(@.title=='Submit')]\n\n# All text fields that are enabled\n$..[?(@.role=='AXTextField' && @.enabled==true)]\n\n# Elements with accessibility identifiers\n$..[?(@.ax_identifier=='loginButton')]\n\n# Elements in a specific app\n$.processes[?(@.name=='Calculator')]..[?(@.role=='AXButton')]\n```\n\n## \ud83e\uddea Perfect for App Testing\n\nThis tool shines when developing and testing Mac applications:\n\n### Test Automation\n```\n\"Test my login flow:\n1. Find the username field and type 'testuser' \n2. Find the password field and type 'password123'\n3. Click the login button\n4. Verify a success message appears\"\n```\n\n### UI Validation\n```\n\"Check my settings window:\n- Are all buttons properly labeled?\n- Are there any text fields without accessibility identifiers?\n- Click the screenshot button to capture the current state\"\n```\n\n### Accessibility Auditing\n```\n\"Audit my app for accessibility:\n- Find all interactive elements without accessibility labels\n- Check if keyboard navigation works properly\n- Identify any elements that might be hard to use\"\n```\n\n## \ud83d\udcf8 Adding Screenshots to Your App\n\nWe don't provide built-in screenshot functionality, but you can easily add it to your Mac app! Check out our [complete Swift implementation example](examples/screenshot.swift) based on a real-world app.\n\n**Key points:**\n- Uses `ScreenCaptureKit` (macOS 14+) for high-quality captures\n- Automatically finds your app window\n- Saves timestamped screenshots to Documents/Screenshots\n- Integrates perfectly with this MCP - just add an accessibility identifier!\n\n**Usage with Playwright MCP:**\n```\n\"Click the screenshot button to capture the current window\"\n```\n\nThe MCP will find your button by accessibility ID and trigger the screenshot!\n\n## \ud83d\udce6 Development Setup\n\nFor contributors and advanced users:\n\n```bash\n# Clone and install\ngit clone https://github.com/mb-dev/macos-ui-automation-mcp.git\ncd macos-ui-automation-mcp\nuv sync --dev\n\n# Run tests\nuv run python -m pytest tests/ -v\n\n# Check code quality \nuv run ruff check src/ tests/ mcp_server_wrapper.py\nuv run ruff format\n\n# Test the MCP server\nuv run macos-ui-automation-mcp\n```\n\n## \ud83e\udd1d Contributing & Bug Reports\n\nI have limited time to fix issues, so here's the deal:\n\n- \ud83d\udc1b **Found a bug?** File an issue, but please include:\n - Your macOS version\n - Steps to reproduce\n - What you expected vs what happened\n \n- \ud83d\udee0 **Want it fixed faster?** The best way is to:\n 1. Fork the repo\n 2. Write a failing test that reproduces the bug\n 3. Fix the bug\n 4. Submit a PR\n\n- \u2728 **Want a feature?** Same deal - code it up and submit a PR!\n\nI'm happy to review PRs and provide guidance, but I can't promise quick fixes for reported issues. The codebase is well-tested and documented, so dive in! \ud83d\ude80\n\n## \ud83d\udd27 Architecture\n\nBuilt with:\n- **FastMCP** - MCP server framework\n- **PyObjC** - macOS accessibility API bindings \n- **Pydantic** - Type-safe data models\n- **JSONPath** - Powerful element querying\n- **Comprehensive test suite** - Fake system for testing without real UI\n\n## \u26a0\ufe0f Important Notes\n\n### Accessibility Permissions\n- Must be granted to the **parent application** (Terminal, VS Code, etc.)\n- Not to Python or the MCP server itself\n- Required for any UI automation on macOS\n\n### Screenshot Permissions\n- If your app has screenshot functionality, it needs **Screen Recording** permission\n- Add your app to `System Settings \u2192 Privacy & Security \u2192 Screen Recording`\n- This is separate from accessibility permissions\n\n### Performance Tips\n- Use app-specific searches when possible (`find_elements_in_app`)\n- Shallow searches are faster for overviews\n- Deep searches are thorough but slower\n\n### Limitations\n- Requires accessibility API access (some apps restrict this)\n- Works best with native macOS applications\n- Some system-level elements may not be accessible\n\n## \ud83d\udcc4 License\n\nMIT License - feel free to use this in your projects!\n\n## \ud83c\udfad Why \"Playwright for Mac\"?\n\nJust like Playwright revolutionized web testing by providing a simple API to control browsers, this tool does the same for native macOS applications. Instead of writing complex GUI automation scripts, just tell Claude what you want to test or automate in natural language.\n\nPerfect for the age of AI-assisted development! \ud83e\udd16\n\n---\n\n**Need help?** Check the [examples/](examples/) folder or [open an issue](https://github.com/mb-dev/macos-ui-automation-mcp/issues). Better yet, submit a PR! \ud83d\ude04",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for macOS UI automation with Claude Desktop/Code integration, plus Python library and CLI interfaces",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/mb-dev/macos-ui-automation-mcp#readme",
"Homepage": "https://github.com/mb-dev/macos-ui-automation-mcp",
"Issues": "https://github.com/mb-dev/macos-ui-automation-mcp/issues",
"Repository": "https://github.com/mb-dev/macos-ui-automation-mcp.git"
},
"split_keywords": [
"accessibility",
" automation",
" claude",
" jsonpath",
" macos",
" mcp",
" ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "49423af4da0438b30d9361df7d35898803a8f3ff096e9fd92ab1f72c665ff9a0",
"md5": "ab8f85afd6a6c137e452429366cf7629",
"sha256": "04bc5b02569354cdf77ce9a28f1f8f15fd4705a0c2d6209a1f1048b2cb8d7885"
},
"downloads": -1,
"filename": "macos_ui_automation_mcp-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab8f85afd6a6c137e452429366cf7629",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 44616,
"upload_time": "2025-08-02T04:45:10",
"upload_time_iso_8601": "2025-08-02T04:45:10.816649Z",
"url": "https://files.pythonhosted.org/packages/49/42/3af4da0438b30d9361df7d35898803a8f3ff096e9fd92ab1f72c665ff9a0/macos_ui_automation_mcp-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0446f400bc372b968b0ee190f905481f5f3c7bf0c556448cb25871050c97749",
"md5": "964c948e6f3b1caf1d4361f8f1f0d4e7",
"sha256": "0a19ce9ce9e04489e923a04b365b809a9f660aa0027c04a18916bef09700312b"
},
"downloads": -1,
"filename": "macos_ui_automation_mcp-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "964c948e6f3b1caf1d4361f8f1f0d4e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 134615,
"upload_time": "2025-08-02T04:45:12",
"upload_time_iso_8601": "2025-08-02T04:45:12.237572Z",
"url": "https://files.pythonhosted.org/packages/f0/44/6f400bc372b968b0ee190f905481f5f3c7bf0c556448cb25871050c97749/macos_ui_automation_mcp-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 04:45:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mb-dev",
"github_project": "macos-ui-automation-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "macos-ui-automation-mcp"
}
JSON
