🍏 macOS Computer Use (MCP Server)

超高速でネイティブな Model Context Protocol (MCP) サーバー。LLMや自律エージェントに、macOS上での視覚的検査とフェイルクローズドなデスクトップ自動化を提供します。

コンパイルされたSwiftコアで構築され、Appleのネイティブな CoreGraphics、Vision OCR (VNRecognizeTextRequest)、Accessibility APIs を活用して、セマンティックなバックグラウンドアクションを実行します。ターゲット指定のない入力は、明示的なグローバルCoreGraphicsフォールバックとして残ります。

⚡ 主なハイライト

• 🎯 ネイティブ Apple Vision OCR (find_text / click_text): 表示されているテキストを、明示的な exact、word、prefix、substring のマッチングで検出し、オカレンスが選択されない限り曖昧なクリックを拒否します。

• 🛡️ フェイルクローズドなターゲティング: windowId が権威を持ちます。無効なIDやアプリ/ウィンドウの不一致は、別のウィンドウやディスプレイ全体にフォールバックする代わりにエラーを返します。

• 🔐 デフォルトで安全: グローバルなポインタ/キーボード入力、フォアグラウンドアプリのアクティベーション、カスタムAppleScriptは、MCPプロセスが MACOS_COMPUTER_USE_UNSAFE=1 で開始されない限り無効です。

• 🩺 権限プレフライト: get_capabilities は、macOSの権限要求APIを呼び出さずに、アクセシビリティ、画面収録、イベント合成の準備状況を報告します。

• ♿ バックグラウンドアクセシビリティアクション: アプリケーションをアクティブにせずに、コントロールの検査、値の設定、セマンティックアクションの実行、編集可能なコントロールのターゲット指定ができます。

• ⏱️ セマンティックバックグラウンド待機: スクリーンショットを撮ったり画面収録を必要とせずに、アクセシビリティコントロールが表示されるのを待ちます。

• 🖱️ ライブエージェントカーソル: クリックやスクロールは、特徴的なクリックスルーカーソルオーバーレイをターゲットまで滑らせ、成功または失敗のフィードバックを表示し、アイドル時には物理ポインタを動かさずにフェードします。

• 👁️ スクリーンショットカーソルの一致 (mark_cursor): 返されるアクションスクリーンショットは、ターゲット座標に同じエージェントカーソルを描画します。

• ⚡ リアクティブUI同期 (wait_for_text): 盲目的な sleep() タイムアウトを、動的なオートコンプリートドロップダウン、モーダル、状態変化が現れた瞬間に解決する高速OCRポーリングループに置き換えます。

• 🖼️ ウィンドウ分離スクリーンキャプチャ: ウィンドウを前面に持ってきたり、重なっているウィンドウをキャプチャしたりせずに、ターゲットアプリケーションのバッファをバックグラウンドでクリーンにキャプチャします（screencapture -l <wid> -o -x）。

Related MCP server: ScreenHand

🛠️ 公開ツール

🚀 インストールとセットアップ

npxで実行

MCPクライアントを設定して、最新の公開パッケージをダウンロード、ビルド、起動します：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"]
    }
  }
}

このパッケージには、Apple SiliconおよびIntel Mac向けのアドホック署名されたユニバーサルSwiftヘルパーが含まれているため、npx はローカルのSwiftコンパイラやインストールスクリプトの承認を必要としません。

デフォルト設定では、セマンティックバックグラウンド自動化と読み取り専用の検査が公開されます。意図的にグローバルなポインタ/キーボード入力、フォアグラウンドアクティベーション、または任意のAppleScriptを必要とするワークフローの場合は、明示的にオプトインしてください：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"],
      "env": {
        "MACOS_COMPUTER_USE_UNSAFE": "1"
      }
    }
  }
}

1. 前提条件

• macOS 13.0+（Apple Silicon または Intel）

• Node.js 20+

• Xcode Command Line Tools はソースからビルドする場合のみ必要です：

  xcode-select --install

2. クローンとビルド

git clone https://github.com/johnexzy/macos-computer-use.git
cd macos-computer-use
npm install
npm run build

🔒 機能ベースのmacOS権限

使用するツールに必要な権限のみを付与してください。macOSは、MCPサーバーを実行しているホストアプリケーション（Terminal、OpenCode、Cursor、VS Codeなど）に権限を帰属させます：

1. アクセシビリティ: セマンティックな検査とアクションに必要です。画面収録は必要ありません。

2. 画面およびシステムオーディオ収録: screenshot、find_text、click_text、wait_for_text などのスクリーンショットおよびVision OCRツールにのみ必要です。

3. イベント合成: 非安全モードのグローバルCoreGraphicsクリック、タイピング、キー押下、スクロールには、イベント送信アクセスが必要です。セマンティックアクセシビリティアクションはこのグローバルフォールバックを使用しません。

4. 自動化: 非安全モードが有効で、run_applescript が別のアプリケーションにイベントを送信する場合にのみ、macOSによって要求されます。コア入力およびバックグラウンドツールは、System Eventsの代わりにネイティブヘルパーを使用します。

保護された操作の前に get_capabilities を呼び出してください。権限検査はAppleのプレフライトAPIを使用し、権限プロンプトを開きません。アクセスがない場合、スクリーンショット/OCRおよびグローバル入力パスは、ディスパッチ前に SCREEN_RECORDING_PERMISSION_REQUIRED または INPUT_POSTING_PERMISSION_REQUIRED を返します。システム設定で手動でアクセスを許可し、ホストが古いプライバシー状態を保持している場合はMCPを再接続してください。

macOSは、新しく付与されたプライバシー権限の後にホストアプリの再起動を要求する場合があります。これはmacOSによって強制されます。サーバーは繰り返しプロンプトを表示したり、無関係な権限を要求したりしません。

バックグラウンドUI自動化は協力的です：macOSは別のプロセス内のアクセシビリティ要素に対処できますが、アプリケーションがターゲット指定されたキーボードイベントを無視したり、後のリリースで識別子を変更したりする場合があります。これらのツールは、アプリをアクティブにしたり誤った成功を報告したりする代わりに、明示的な未サポート/未確認エラーを返します。

🔌 MCP設定

このサーバーをMCPクライアント設定に追加します：

Antigravity / Claude Desktop / Cursor / Windsurf

mcp_config.json / claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/macos-computer-use/server.mjs"]
    }
  }
}

🧪 ネイティブSwiftヘルパーの直接テスト

ネイティブバイナリをターミナルから直接テストできます：

# Display resolution and scaling
./native_helper size

# List active Chrome windows in Z-order
./native_helper list_windows "Google Chrome"

# Find a button or text on screen with Apple Vision OCR in ~30ms
./native_helper find_text "Search" "Google Chrome"

# Reactively wait for dynamic text to appear
./native_helper wait_for_text "quantum" "Google Chrome" nil 5.0

自動化されたフェイルクローズドおよびマッチング回帰テストを実行します：

npm test

バックグラウンドのCalculatorウィンドウに対するセマンティック検査を検証します：

npm run test:background -- Calculator

CalculatorとSystem Settingsを開いた状態で、ライブネイティブアプリのスモークスイートを実行します。このテストは、AppleScriptを使用してTextEditフィクスチャを作成およびクリーンアップするため、非安全モードをオプトインします：

npm run test:live

変更を加えるツールの結果には、バージョン管理されたコントラクト、配信方法、検証レベル、フォアグラウンド保持状態、ターゲットを含む execution オブジェクトが含まれます。座標ベースのアクションは status: "delivered_unverified" を保持します。結果として生じる後続状態を、セマンティック検査、OCR、またはスクリーンショットで検証してください。

MCPサーバーは、最初のクリックまたはスクロール時に1つのカーソルオーバーレイプロセスを遅延起動し、MCP接続が閉じると停止します。オーバーレイはマウス入力をインターセプトせず、すべてのSpacesおよびフルスクリーンウィンドウに参加し、AppKitが表示できない場合は要求されたアクションをブロックせずに cursorOverlay.status: "unavailable" を報告します。

📦 公開

main へのプッシュはnpm公開ワークフローを実行します。新しいバージョンをリリースするには、マージ前に package.json と package-lock.json のバージョンを更新してください。npmに既に存在するバージョンはテストされ、スキップされます。

📄 ライセンス

MIT © John Oba