🍏 macOS Computer Use (MCP Server)

LLM과 자율 에이전트에게 macOS에서의 시각적 검사와 fail-closed 데스크톱 자동화를 제공하는 초고속 네이티브 Model Context Protocol (MCP) 서버입니다.

Apple의 네이티브 CoreGraphics, Vision OCR (VNRecognizeTextRequest), 그리고 의미론적 백그라운드 작업을 위한 Accessibility API를 활용하는 컴파일된 Swift 코어로 구축되었습니다. 대상이 지정되지 않은 입력은 명시적인 전역 CoreGraphics 폴백으로만 유지됩니다.

⚡ 주요 특징

• 🎯 네이티브 Apple Vision OCR (find_text / click_text): 명시적인 exact, word, prefix 또는 substring 매칭으로 표시된 텍스트를 찾고, 발생 항목이 선택되지 않은 경우 모호한 클릭을 거부합니다.

• 🛡️ Fail-Closed 타겟팅: windowId가 권위 있는 값입니다. 잘못된 ID와 앱/창 불일치는 다른 창이나 전체 디스플레이로 폴백하는 대신 오류를 반환합니다.

• 🔐 기본적으로 안전: MCP 프로세스가 MACOS_COMPUTER_USE_UNSAFE=1로 시작되지 않는 한 전역 포인터/키보드 입력, 포그라운드 앱 활성화, 사용자 지정 AppleScript가 비활성화됩니다.

• 🩺 권한 사전 점검: get_capabilities는 macOS 권한 요청 API를 호출하지 않고 접근성, 화면 녹화, 이벤트 합성 준비 상태를 보고합니다.

• ♿ 백그라운드 접근성 작업: 애플리케이션을 활성화하지 않고 컨트롤 검사, 값 설정, 의미론적 작업 실행, 편집 가능한 컨트롤 타겟팅이 가능합니다.

• ⏱️ 의미론적 백그라운드 대기: 화면 캡처나 화면 녹화 권한 없이 접근성 컨트롤이 나타날 때까지 대기합니다.

• 🖱️ 실시간 에이전트 커서: 클릭과 스크롤 시 물리적 포인터를 움직이지 않고 독특한 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"]
    }
  }
}

패키지에는 Apple Silicon 및 Intel Mac용 ad-hoc 서명된 유니버설 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. 접근성(Accessibility): 의미론적 검사 및 작업에 필요합니다. 화면 녹화 권한은 필요하지 않습니다.

2. 화면 및 시스템 오디오 녹화: screenshot, find_text, click_text, wait_for_text와 같은 스크린샷 및 Vision OCR 도구에만 필요합니다.

3. 이벤트 합성: 비안전 모드 전역 CoreGraphics 클릭, 타이핑, 키 입력, 스크롤에는 이벤트 전송 접근이 필요합니다. 의미론적 접근성 작업은 이 전역 폴백을 사용하지 않습니다.

4. 자동화(Automation): 비안전 모드가 활성화되고 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

자동화된 fail-closed 및 일치 회귀 테스트 실행:

npm test

백그라운드 계산기 창에 대한 의미론적 검사 확인:

npm run test:background -- Calculator

계산기와 시스템 설정이 열린 상태에서 실시간 네이티브 앱 스모크 스위트를 실행하세요. 이 테스트는 TextEdit 픽스처를 생성하고 정리하기 위해 AppleScript를 사용하므로 비안전 모드를 옵트인합니다:

npm run test:live

변경 도구 결과에는 버전이 지정된 계약, 전달 방법, 검증 수준, 포그라운드 보존 상태 및 대상을 포함하는 execution 객체가 포함됩니다. 좌표 기반 작업은 status: "delivered_unverified"를 유지합니다. 중요한 사후 상태는 의미론적 검사, OCR 또는 스크린샷으로 검증하세요.

MCP 서버는 첫 번째 클릭 또는 스크롤 시 지연 방식으로 하나의 커서 오버레이 프로세스를 시작하고 MCP 연결이 닫히면 중지합니다. 오버레이는 마우스 입력을 가로채지 않으며, 모든 Spaces 및 전체 화면 창에 참여하고, AppKit이 표시할 수 없는 경우 요청된 작업을 차단하지 않고 cursorOverlay.status: "unavailable"을 보고합니다.

📦 배포

main 브랜치에 푸시하면 npm 배포 워크플로가 실행됩니다. 새 버전을 릴리스하려면 병합 전에 package.json과 package-lock.json의 버전을 업데이트하세요. npm에 이미 존재하는 버전은 테스트 후 건너뜁니다.

📄 라이선스

MIT © John Oba