Claude가 당신의 Mac을 제어하게 하세요. 창 이동, 메뉴 클릭, 텍스트 입력, 클립보드 읽기, 브라우저 탭 관리 — 입력 검증(input validation) 및 보안 가드레일(security guardrails)을 갖춘 12가지 타입 도구(typed tools).

{
"mcpServers": {
"osascript": {
...

이 내용을 Claude Desktop 설정(Settings → Developer → Edit Config)에 추가하고, Claude를 재시작하면 준비가 완료됩니다.

다른 클라이언트(Cursor, VS Code, Claude Code)를 위한 설정

Cursor / VS Code (Copilot)

{
"mcpServers": {
"osascript": {
...

Claude Code

claude mcp add osascript -- npx -y mcp-osascript

소스로부터 설치 (개발용)

git clone https://github.com/m0rvayne/mcp-osascript.git
cd mcp-osascript && npm install
# 그 다음 사용: "command": "node", "args": ["/path/to/mcp-osascript/server/index.js"]

설치가 완료되면 Claude에게 다음과 같이 요청해 보세요:

프롬프트 (Prompt)	발생하는 일
"Open Safari and show me what tabs I have"	Safari를 실행하고 모든 탭의 제목과 URL을 읽습니다
"Move the Finder window to the left half of my screen"	창의 크기를 조절하고 위치를 이동합니다
"Click File → Export as PDF in Keynote"	메뉴 바를 탐색하여 해당 항목을 클릭합니다
"Copy the URL from my active Chrome tab"	브라우저 탭을 읽어 활성화된 탭을 찾습니다
"Type 'Hello World' into the active text field"	키보드 입력을 시뮬레이션합니다
"Show a notification when you're done"	네이티브 macOS 배너를 표시합니다
"What app am I using right now?"	최상단 앱 이름과 번들 ID(bundle ID)를 반환합니다
"Press Cmd+Shift+4"	스크린샷 단축키를 실행합니다
"List all items in the Edit menu of VS Code"	메뉴 바를 조사(introspects)합니다
"Close the second window of Terminal"	인덱스(index)를 통해 특정 창을 대상으로 지정합니다

입력 검증(input validation), 오류 분류(error classification), 그리고 권한 인식 오류 메시지(permission-aware error messages)를 갖춘 12가지 타입 도구입니다.

도구 (Tool)	기능	권한
run_osascript	모든 AppleScript 또는 JXA 스크립트 실행	없음
get_clipboard	클립보드를 텍스트로 읽기	없음
set_clipboard	클립보드에 텍스트 쓰기	없음
send_notification	macOS 알림 배너 표시	없음
open_url	브라우저에서 URL 열기 (http/https/mailto만 가능)	없음
open_app	앱 실행 또는 앱을 전면으로 가져오기	없음
get_frontmost_app	활성화된 앱 이름 + 번들 ID (bundle ID) 가져오기	자동화 (Automation)
get_browser_tabs	Safari, Chrome 또는 Arc의 탭 목록 가져오기	자동화 (Automation)
type_text	활성화된 앱에 텍스트 입력 (최대 500자)	접근성 (Accessibility)
press_key	수정 키와 함께 키 누르기 (cmd+c, return, f5)	접근성 (Accessibility)
manage_windows	목록화 / 이동 / 크기 조정 / 최소화 / 전체 화면 / 닫기	접근성 (Accessibility)
app_menu	모든 앱의 메뉴 항목 목록화 또는 클릭	접근성 (Accessibility)

Claude가 존재하지 않는 메뉴 항목을 클릭하려고 하면, 서버는 해당 레벨에서 사용 가능한 항목 목록을 자동으로 반환합니다. 따라서 Claude는 올바른 이름으로 다시 시도할 수 있습니다. 다른 어떤 MCP 서버도 이 기능을 제공하지 않습니다.

사용자: "미리보기(Preview)에서 파일 → PDF로 내보내기 클릭해줘"
Claude: app_menu click ["File", "Export as PDF"] 호출
서버: "'File' 메뉴에서 'Export as PDF' 항목을 찾을 수 없습니다.
...

mcp-osascript	steipete (824★)	peakmojo (463★)
검증 기능이 포함된 타입 지정 도구 (Typed tools)	12	2 (generic)	1 (generic)
URL 스킴 허용 목록 (URL scheme allowlist)	http/https/mailto	아니요	아니요
환경 격리 (자식 프로세스)	PATH+HOME+LANG만 허용	전체 process.env	전체 process.env
프로세스 그룹 종료 (고아 프로세스 방지)	SIGTERM→SIGKILL	아니요	아니요
오류 정화 (경로, 토큰)	예	아니요	아니요
프로토타입 오염 방지 (Prototype pollution protection)	Object.create(null)	아니요	아니요
자기 수정 메뉴 클릭 (Self-correcting menu click)	예	아니요	아니요
통합 테스트 (Integration tests)	41	0	0
Stdin 파이핑 (임시 파일 미사용)	예	임시 파일 사용	임시 파일 사용

도구는 세 가지 계층에서 작동합니다:

권한 불필요— 클립보드(clipboard), 알림(notifications), URL, 앱(apps). 즉시 작동합니다. 자동화 (Automation)— 브라우저 탭, 최상위 앱(frontmost app). 브라우저당 한 번의 macOS 프롬프트가 발생합니다. 손쉬운 사용 (Accessibility)— 키보드, 윈도우, 메뉴. **시스템 설정 (System Settings) → 개인정보 보호 및 보안 (Privacy & Security) → 손쉬운 사용 (Accessibility)**에서 한 번만 허용하면 됩니다.

권한이 누락된 경우, 서버는 정확히 무엇을 해야 하는지 알려줍니다:

"Accessibility permission required. Grant access to 'osascript' in System Settings > Privacy & Security > Accessibility."

npm test

12개의 모든 도구를 다루는 41개의 통합 테스트 (integration tests) — 입력 유효성 검사 (input validation), 보안 경계 (URL 스킴 차단, 프로토타입 오염 (prototype pollution), 스크립트 크기 제한), 타임아웃 강제 적용, 권한 오류 처리 포함.

보안 및 아키텍처 (Security & Architecture)

run_osascript는 임의의 코드 (arbitrary code)를 실행합니다 — 이는 설계 의도입니다. MCP 클라이언트 (Claude)가 신뢰 경계 (trust boundary) 역할을 합니다.

• 스크립트는 stdin을 통해 /usr/bin/osascript로 파이핑 (piped) 됩니다 — 임시 파일 미사용, TOCTOU 레이스 컨디션 (race conditions) 없음.

• 스크립트 크기: 최대 50 KB. 출력: 최대 50K 자 (truncated, 잘림).

• 오류 메시지 정화 (sanitized) — 파일 시스템 경로, 토큰, 비밀번호는 제거됩니다.

• 자식 프로세스 (Child processes)는 최소한의 환경 변수(PATH, HOME, LANG)만 가집니다 — API 키나 비밀 정보가 유출되지 않습니다.

• URL 스킴 허용 목록 (allowlist) — file://, smb://, vnc://, javascript: 모두 차단됩니다.

• 핸들러 디스패치 (Handler dispatch)는 Object.create(null)을 사용합니다 — 프로토타입 오염 (prototype pollution) 방지.

• 타임아웃 시 프로세스 그룹 종료 — SIGTERM → 2초 유예 기간 → SIGKILL. 고아 프로세스 (orphaned processes) 없음.

• 동시성 세마포어 (Concurrency semaphore) — 최대 5개의 osascript 프로세스 동시 실행.

• 우아한 종료 (Graceful shutdown) — 10초 강제 종료 안전망과 함께 server.close() 실행.

• 오류 분류 (Error classification) — macOS 오류 코드 (-1728, -1743, -25211)를 실행 가능한 메시지로 파싱합니다. 영어 및 러시아어 로케일 (locales)을 지원합니다.

• macOS 13+ (Ventura 이상)

• Node.js 18+

MIT