🚀 macOS用Playwright MCP 🎭
このツールは、Playwrightのように、自然言語でmacOSアプリケーションを制御できるものです。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（Model Context Protocol）サーバーで、ClaudeにあらゆるmacOSアプリケーションを視認し、対話する能力を与えます。Playwrightがウェブブラウザーに対して行うことと同じように、ネイティブのMacアプリに対しても同様のことができます。
最適な用途:
- 🧪 Macアプリケーションのテスト - "自分のアプリ内のログインフローをテストして"
- 🔍 アプリ開発 - "すべてのボタンが適切にラベル付けされているか確認して"
- 🤖 UI自動化 - "このフォームに入力して送信して"
- 📱 アプリ探索 - "Finder内のすべての対話可能な要素を表示して"
🛠 利用可能なツール
| ツール |
説明 |
使用例 |
find_elements |
JSONPathを使用してUI要素を見つける |
"すべてのテキストフィールドを表示して" |
find_elements_in_app |
特定のアプリ内を検索する |
"Safari内のボタンを見つけて" |
click_by_accessibility_id |
アクセシビリティアクションを使用してクリックする |
"送信ボタンをクリックして" |
click_at_position |
画面座標でクリックする |
"位置 (100, 200) をクリックして" |
type_text_to_element_by_selector |
要素にテキストを入力する |
"検索フィールドに 'hello' を入力して" |
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+）を使用します。
- 自動的にアプリウィンドウを見つけます。
- タイムスタンプ付きのスクリーンショットをDocuments/Screenshotsに保存します。
- この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
uv run macos-ui-automation-mcp
🤝 コントリビューションとバグレポート
問題を修正する時間が限られているため、以下の通りです。
-
🐛 バグを見つけた場合：イシューを登録してください。ただし、以下を含めてください。
- あなたのmacOSバージョン
- 再現手順
- 期待した結果と実際の結果
-
🛠 もっと早く修正してほしい場合：最善の方法は以下の通りです。
- リポジトリをフォークします。
- バグを再現する失敗するテストを書きます。
- バグを修正します。
- PRを提出します。
-
✨ 新機能が欲しい場合：同じようにコードを書いてPRを提出してください！
PRをレビューし、ガイダンスを提供することは喜んで行いますが、報告された問題の迅速な修正を保証することはできません。コードベースは十分にテストされ、文書化されているので、是非挑戦してみてください！ 🚀
🔧 アーキテクチャ
以下を使用して構築されています。
- FastMCP - MCPサーバーフレームワーク
- PyObjC - macOSアクセシビリティAPIバインディング
- Pydantic - 型安全なデータモデル
- JSONPath - 強力な要素クエリ
- 包括的なテストスイート - 実際のUIを使用せずにテストするための仮想システム
⚠️ 重要な注意事項
アクセシビリティ権限
- 親アプリケーション（ターミナル、VS Codeなど）に付与する必要があります。
- PythonやMCPサーバー自体ではなく、親アプリに付与する必要があります。
- macOSでのUI自動化には必須です。
スクリーンショット権限
- アプリにスクリーンショット機能がある場合、画面録画権限が必要です。
システム設定 → プライバシーとセキュリティ → 画面録画にアプリを追加します。- これはアクセシビリティ権限とは別です。
パフォーマンスのヒント
- 可能な場合はアプリ固有の検索を使用してください (
find_elements_in_app)。
- 概要を取得するには浅い検索の方が速いです。
- 深い検索は徹底的ですが、遅くなります。
制限事項
- アクセシビリティAPIへのアクセスが必要です（一部のアプリはこれを制限しています）。
- ネイティブのmacOSアプリケーションで最適に動作します。
- 一部のシステムレベルの要素にはアクセスできない場合があります。
📄 ライセンス
MITライセンスです - 自由にあなたのプロジェクトで使用してください！
🎭 なぜ「Mac用Playwright」なのか？
PlaywrightがシンプルなAPIを提供してウェブテストを革新したように、このツールはネイティブのmacOSアプリケーションに対しても同じことを行います。複雑なGUI自動化スクリプトを書く代わりに、Claudeに自然言語でテストや自動化したいことを伝えるだけです。
AI支援開発の時代に最適です！ 🤖
ヘルプが必要ですか？ examples/フォルダを確認するか、イシューを開く をお試しください。もっと良いのは、PRを提出することです！ 😄
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
