🍏 macOS Computer Use (MCP Server)

Сверхбыстрый нативный Model Context Protocol (MCP) сервер, который предоставляет LLM и автономным агентам визуальный осмотр и автоматизацию рабочего стола на macOS с отказом по умолчанию (fail-closed).

Создан на компилируемом ядре Swift с использованием нативных CoreGraphics, Vision OCR (VNRecognizeTextRequest) и Accessibility API от Apple для семантических фоновых действий. Ненаправленный ввод остаётся явным глобальным запасным вариантом CoreGraphics.

⚡ Ключевые особенности

• 🎯 Нативный Apple Vision OCR (find_text / click_text): Находит видимый текст с явным сопоставлением exact, word, prefix или substring и отказывается от неоднозначных кликов, если не выбран конкретный экземпляр.

• 🛡️ Нацеливание с отказом по умолчанию: windowId является авторитетным. Недействительные идентификаторы и несоответствия приложения/окна возвращают ошибки вместо перехода к другому окну или всему дисплею.

• 🔐 Безопасно по умолчанию: Глобальный ввод указателя/клавиатуры, активация переднего приложения и пользовательский AppleScript отключены, если процесс MCP не запущен с MACOS_COMPUTER_USE_UNSAFE=1.

• 🩺 Предварительная проверка разрешений: get_capabilities сообщает о готовности Accessibility, Screen Recording и синтеза событий без вызова API запроса разрешений macOS.

• ♿ Фоновые действия Accessibility: Проверка элементов управления, установка значений, выполнение семантических действий и нацеливание на редактируемые элементы управления без активации их приложения.

• ⏱️ Семантическое фоновое ожидание: Ожидает появления элементов управления Accessibility без создания снимка экрана или требования Screen Recording.

• 🖱️ Живой курсор агента: Клики и прокрутка плавно перемещают отличительный курсор-оверлей (click-through) к цели, показывают обратную связь об успехе или неудаче и исчезают в режиме ожидания, не перемещая ваш физический указатель.

• 👁️ Совпадающий курсор на скриншоте (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"]
    }
  }
}

Пакет включает ad-hoc подписанный универсальный Swift-хелпер для Apple Silicon и Intel Mac, поэтому 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. Accessibility: Требуется для семантической инспекции и действий. Не требует Screen Recording.

2. Screen & System Audio Recording: Требуется только для скриншотов и инструментов Vision OCR, таких как screenshot, find_text, click_text и wait_for_text.

3. Синтез событий: Глобальные клики CoreGraphics, ввод текста, нажатия клавиш и прокрутка в небезопасном режиме требуют доступа к отправке событий. Семантические действия Accessibility не используют этот глобальный запасной вариант.

4. Automation: Может быть запрошено macOS только при включённом небезопасном режиме и когда run_applescript отправляет событие другому приложению. Основные инструменты ввода и фоновые инструменты используют нативный хелпер вместо System Events.

Вызывайте get_capabilities перед защищёнными операциями. Проверка разрешений использует предварительные API Apple и не открывает запрос разрешения. Если доступ отсутствует, пути скриншотов/OCR и глобального ввода возвращают SCREEN_RECORDING_PERMISSION_REQUIRED или INPUT_POSTING_PERMISSION_REQUIRED перед отправкой. Предоставьте доступ вручную в System Settings, затем переподключите MCP, если хост всё ещё хранит устаревшее состояние конфиденциальности.

macOS может потребовать перезапуска хост-приложения после недавно предоставленного разрешения конфиденциальности. Это обеспечивается macOS; сервер не запрашивает повторно и не запрашивает несвязанные разрешения.

Фоновая автоматизация UI является кооперативной: macOS может обращаться к элементам Accessibility в другом процессе, но приложение может игнорировать целевые события клавиатуры или изменять свои идентификаторы в более поздней версии. Эти инструменты возвращают явные ошибки неподдержки/неподтверждения в таких случаях вместо активации приложения или сообщения о ложном успехе.

🔌 Конфигурация 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

Проверьте семантическую инспекцию фонового окна Калькулятора:

npm run test:background -- Calculator

С открытыми Калькулятором и System Settings запустите живой набор тестов нативного приложения. Тест включает небезопасный режим, потому что использует AppleScript для создания и очистки фикстур TextEdit:

npm run test:live

Результаты изменяющих инструментов включают объект execution с версионированным контрактом, методом доставки, уровнем проверки, состоянием сохранения переднего плана и целью. Действия на основе координат сохраняют status: "delivered_unverified"; проверяйте значимое последующее состояние с помощью семантической инспекции, OCR или скриншота.

MCP-сервер запускает один процесс оверлея курсора лениво при первом клике или прокрутке и останавливает его при закрытии MCP-соединения. Оверлей никогда не перехватывает ввод мыши, присоединяется ко всем Space и полноэкранным окнам и сообщает cursorOverlay.status: "unavailable" без блокировки запрошенного действия, если AppKit не может его отобразить.

📦 Публикация

Пуш в main запускает рабочий процесс публикации npm. Чтобы выпустить новую версию, обновите версию в package.json и package-lock.json перед слиянием. Версии, которые уже существуют на npm, тестируются и пропускаются.

📄 Лицензия

MIT © John Oba