macos-ui-mcp

Claude がネイティブ macOS アプリの UI を、構築中に検査・操作できるようにする Playwright 風のツール — 画面収録の許可は不要です。

画面をキャプチャする代わりに、アプリ自身が自分をレンダリングします。デバッグ専用の小さな Swift パッケージ（swift-harness/）が、アプリのビューツリーとプロセス内 PNG レンダラーを localhost HTTP で公開します。MCP サーバー（src/）がそれを Claude が呼び出せるツールに変換します：list_windows、get_ui_tree、screenshot、click、type、wait_for、invoke_action。

設計の根拠、アーキテクチャ比較、プロジェクトの目標については IDEA.md を参照してください。

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

レイアウト

Related MCP server: Desktop Pilot MCP

使い方

1. ハーネスを macOS アプリに追加する（DEBUG ビルドのみ）

swift-harness/README.md を参照してください。AppDelegate に 1 行追加するだけです：

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. MCP サーバーをビルドする

npm install
npm run build

3. Claude Code に登録する

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

これで、デバッグビルドでアプリを実行している状態で、Claude に get_ui_tree や screenshot を呼び出すよう依頼できます — 画面収録のプロンプトは表示されません。

開発

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e が目標の証明です：get_ui_tree がコントロールを認識すること、screenshot が実際のプロセス内 PNG を返すこと、click / type がライブ UI を変更すること — すべて画面収録の許可なしで確認できます。

セレクター文法

click、type、screenshot、wait_for で使用します：

click / type は曖昧なセレクター（複数一致）を拒否し、候補の id を報告します。

ステータス

• v0.1 — macOS / AppKit。7 つのツールすべて実装済み。38 のユニットテスト + 実際の Swift ハーネスを通じて showcase/ アプリを操作する 5 ケースのエンドツーエンドテスト。検証済み：ツリー、プロセス内 PNG スナップショット、タップ、テキスト設定、アクションフック — 画面収録オフ。

• 未対応 — SwiftUI ネイティブツリー（現時点では AppKit イントロスペクションのみ）、Windows アダプター、Accessibility API によるサードパーティアプリの検査。

ライセンス

MIT © 2026 Thang Duong