🍏 macOS Computer Use (MCP Server)

초고속, 네이티브 Model Context Protocol (MCP) 서버로, LLM 및 자율 에이전트가 macOS에서 실제 하드웨어 마우스나 키보드 포커스를 가로채지 않고 전체 화면 검사 및 데스크톱 자동화 기능을 사용할 수 있게 합니다.

컴파일된 Swift 코어로 구축되었으며, Apple의 네이티브 CoreGraphics, Vision OCR (VNRecognizeTextRequest), 그리고 직접적인 프로세스 수준 이벤트 라우팅(CGEvent.postToPid)을 활용합니다.

⚡ 주요 특징

• 🎯 30ms 미만 Apple Vision OCR (find_text / click_text): 맹목적인 $(x, y)$ 좌표 추측이 필요 없습니다. 에이전트는 Apple Neural Engine 가속을 사용하여 버튼, 레이블, 텍스트 플레이스홀더를 이름으로 픽셀 단위 정확도로 찾아냅니다.

• 🛡️ 비간섭 백그라운드 실행: 전역 macOS 하드웨어 이벤트 탭에서 분리됩니다. IDE나 브라우저에서 계속 작업하는 동안 클릭, 스크롤, 키 입력을 특정 애플리케이션 PID로 직접 전달할 수 있습니다.

• 👁️ 가상 커서 오버레이 (mark_cursor): 에이전트의 대상 좌표가 스크린샷 프레임에 시각적으로 그려집니다(청록색 타깃 링 + 자홍색 펄스 점). 화면에서 실제 마우스를 움직이지 않습니다.

• ⚡ 반응형 UI 동기화 (wait_for_text): 맹목적인 sleep() 타임아웃을 고속 OCR 폴링 루프로 대체하여 동적 자동 완성 드롭다운, 모달 또는 상태 변경이 나타나는 즉시 해결합니다.

• 🖼️ 창 분리 화면 캡처: 창을 전면으로 가져오거나 겹치는 창을 캡처하지 않고 대상 애플리케이션 버퍼를 백그라운드에서 깔끔하게 캡처합니다(screencapture -l <wid> -o -x).

🛠️ 제공되는 도구

🚀 설치 및 설정

1. 사전 요구 사항

• macOS 13.0+ (Apple Silicon 또는 Intel)

• Node.js 18+

• Xcode Command Line Tools (네이티브 Swift 바이너리 컴파일용):

  xcode-select --install

2. 클론 및 빌드

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

(postinstall 스크립트는 native_helper.swift를 최적화된 네이티브 바이너리로 자동 컴파일합니다).

🔒 필수 macOS 권한

데스크톱 캡처 및 입력 시뮬레이션을 허용하려면 System Settings > Privacy & Security에서 호스트 애플리케이션(Terminal, iTerm2, Antigravity, Cursor 또는 VS Code)에 권한을 부여하세요:

1. 화면 및 시스템 오디오 녹화: screenshot 및 시각적 OCR에 필요합니다.

2. 손쉬운 사용: mouse_click, type_text, press_key에 필요합니다.

🔌 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

📄 라이선스

MIT © John Oba