macOS Automator MCP 서버
개요
이 프로젝트는 macOS에서 AppleScript 및 JavaScript for Automation(JXA) 스크립트를 실행할 수 있는 MCP(Model Context Protocol) 서버인 macos_automator 제공합니다. ID로 접근 가능한 미리 정의된 스크립트의 지식 기반을 제공하며, 인라인 스크립트, 스크립트 파일 및 인수 전달을 지원합니다. 지식 기반은 빠른 서버 시작을 위해 처음 사용 시 지연 로드됩니다.
Related MCP server: AppleScript MCP Server
이익
MCP를 통해 원격으로 AppleScript/JXA 스크립트를 실행합니다.
일반적인 macOS 자동화 작업에 대한 풍부하고 확장 가능한 지식 기반을 활용하세요.
macOS 애플리케이션과 시스템 기능을 프로그래밍 방식으로 제어합니다.
macOS 자동화를 대규모 AI 기반 워크플로에 통합합니다.
필수 조건
Node.js(버전 >=18.0.0 권장,
package.json엔진 참조).맥OS.
중요 권한 설정:
이 MCP 서버를 실행하는 애플리케이션(예: 터미널, Node.js 애플리케이션)에는 서버가 실행되는 macOS 컴퓨터에서 명시적인 사용자 권한이 필요합니다.
자동화 권한: 다른 애플리케이션(Finder, Safari, 메일 등)을 제어합니다.
시스템 설정 > 개인정보 보호 및 보안 > 자동화로 이동합니다.
목록에서 서버를 실행하는 애플리케이션(예: 터미널)을 찾습니다.
제어해야 하는 모든 애플리케이션에 대해 확인란이 선택되어 있는지 확인하세요.
예를 들어
docs/automation-permissions-example.png(플레이스홀더 이미지)를 참조하세요.
접근성 권한: "시스템 이벤트"를 통한 UI 스크립팅(예: 클릭, 키 입력 시뮬레이션)
시스템 설정 > 개인정보 보호 및 보안 > 접근성으로 이동하세요.
서버를 실행하는 애플리케이션(예: 터미널)을 목록에 추가하고 해당 확인란이 선택되어 있는지 확인하세요.
새 애플리케이션을 제어하거나 접근성 기능을 처음 사용하려고 하면 사전 승인이 필요하더라도 macOS 확인 메시지가 표시될 수 있습니다. 서버 자체는 이러한 권한을 부여할 수 없습니다.
설치 및 사용
이 서버를 실행하는 기본 방법은 npx 사용하는 것입니다. 이렇게 하면 글로벌 설치 없이도 최신 버전을 사용할 수 있습니다.
MCP 클라이언트의 mcp.json (또는 동등한 구성)에 다음 구성을 추가합니다.
지엑스피1
로컬에서 실행(개발 또는 직접 사용)
개발 목적이거나 복제된 저장소에서 서버를 직접 실행하고 싶다면 제공된 start.sh 스크립트를 사용할 수 있습니다. 로컬 수정을 하거나 특정 버전을 실행하려는 경우 유용합니다.
저장소를 복제합니다.
git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installedMCP 클라이언트 구성: 복제된 저장소 내의
start.sh스크립트의 절대 경로를 가리키도록 MCP 클라이언트 구성을 업데이트합니다.mcp.json구성 스니펫 예:{ "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } }중요:
/absolute/path/to/your/cloned/macos-automator-mcp/start.sh사용자 시스템의 올바른 절대 경로로 바꾸세요.start.sh스크립트는 컴파일된 버전을 찾을 수 없는 경우 자동으로tsx사용하여 TypeScript 소스를 직접 실행하고,dist/에서 컴파일된 버전을 찾을 수 있는 경우 해당 버전을 실행합니다.LOG_LEVEL환경 변수의 영향을 받습니다.개발자 참고 사항:
start.sh스크립트는 특히 실행 전에 기존에 컴파일된dist/server.js파일을 제거하도록 수정된 경우(예:rm -f dist/server.js추가),tsx를 통해src/디렉터리의 최신 TypeScript 코드를 항상 실행하도록 설계되었습니다. 이는 오래된 빌드 문제를 방지하여 개발 환경에 이상적입니다. 프로덕션 배포(예: npm에 게시)의 경우, 빌드 프로세스는 일반적으로 최종dist/server.js파일을 생성하며, 이는 게시된 패키지의 진입점이 됩니다.
제공된 도구
1. execute_script
macOS에서 AppleScript 또는 JavaScript for Automation(JXA) 스크립트를 실행합니다. 스크립트는 인라인 콘텐츠( script_content ), 절대 파일 경로( script_path )로 제공되거나, 고유 kb_script_id 사용하여 내장된 지식 베이스의 스크립트를 참조하여 제공될 수 있습니다.
스크립트 소스(상호 배타적):
script_content(문자열): 원시 스크립트 코드.script_path(문자열): 스크립트 파일에 대한 절대 POSIX 경로(예:.applescript,.scpt,.js).kb_script_id(문자열): 서버 지식 베이스에서 미리 정의된 스크립트의 ID입니다.get_scripting_tips도구를 사용하여 사용 가능한 스크립트 ID와 기능을 확인하세요.
언어 사양:
language(enum: 'applescript' | 'javascript', 선택 사항): 언어를 지정합니다.kb_script_id사용하는 경우 언어는 지식 기반 스크립트에서 추론됩니다.script_content또는script_path사용하고language생략하면 기본적으로 'applescript'가 사용됩니다.
스크립트에 입력 전달:
arguments(문자열 배열, 선택 사항):script_path의 경우: 스크립트의on run argv(AppleScript) 또는run(argv)(JXA) 핸들러에 표준 인수로 전달됩니다.kb_script_id: 미리 정의된 스크립트가 위치 문자열 인수를 허용하도록 설계된 경우(예:--MCP_ARG_1,--MCP_ARG_2와 같은 플레이스홀더를 대체하는 경우) 사용됩니다.get_scripting_tips에서 스크립트의argumentsPrompt확인하세요.
input_data(JSON 객체, 선택 사항):주로 이름이 지정되고 구조화된 입력을 허용하도록 설계된
kb_script_id스크립트용입니다.이 객체의 값은 스크립트의 플레이스홀더를 대체합니다(예:
--MCP_INPUT:yourKeyName).get_scripting_tips의argumentsPrompt참조하세요.값(문자열, 숫자, 부울, 단순 배열/객체)은 AppleScript 리터럴 대응 값으로 변환됩니다.
기타 옵션:
timeout_seconds(정수, 선택 사항, 기본값: 60): 최대 실행 시간.output_format_mode(enum, 선택 사항, 기본값: 'auto'):osascript출력 형식 플래그를 제어합니다.'auto': (기본값) AppleScript의 경우 사람이 읽을 수 있는 형식(-sh)을 사용하고 JXA의 경우 직접 출력(-s플래그 없음)을 사용합니다.'human_readable':-sh강제로 실행합니다(주로 AppleScript의 경우 사람이 읽을 수 있는 출력).'structured_error':-ss(구조적 오류 보고, 주로 AppleScript용)를 강제로 적용합니다.'structured_output_and_error':-s ss(주로 AppleScript에 대한 주요 결과 및 오류에 대한 구조화된 출력)를 강제로 실행합니다.'direct':-s플래그를 사용하지 않습니다(JXA에 권장되며,auto모드에서도 JXA의 동작입니다).
include_executed_script_in_output(부울, 선택 사항, 기본값: false): true인 경우, 출력에 전체 스크립트 내용(지식 기반 스크립트에 대한 모든 대체 항목 이후) 또는 실행된 스크립트 경로가 포함됩니다. 이는 출력 내용 배열에 추가 텍스트 부분으로 추가됩니다.include_substitution_logs(부울, 선택 사항, 기본값: false): true인 경우, 지식 기반 스크립트에서 수행된 플레이스홀더 대체에 대한 자세한 로그가 출력에 포함됩니다. 이 설정은input_data와arguments처리되어 스크립트에 삽입되는 방식을 디버깅하는 데 유용합니다. 로그는 스크립트 출력이 성공하면 스크립트 출력 앞에 추가되고, 실패하면 오류 메시지 뒤에 추가됩니다.report_execution_time(부울, 선택 사항, 기본값: false):true인 경우, 형식화된 스크립트 실행 시간이 포함된 추가 메시지가 응답 콘텐츠 배열에 포함됩니다.
보안 경고 및 macOS 권한: (임의 스크립트 실행 및 macOS 자동화/접근성 권한에 대한 이전과 동일한 중요 경고).
예:
(인라인/파일 경로에 대한 기존 예는 여전히 관련성이 있음)
ID로 지식 기반 스크립트 사용:
{ "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }input_data{ "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }
응답 형식:
execute_script 도구는 다음 형식으로 응답을 반환합니다.
content: 스크립트 출력을 포함하는 텍스트 콘텐츠 항목의 배열isError: (부울, 선택 사항) 스크립트 실행 시 오류가 발생하면true로 설정됩니다. 이 플래그는 다음과 같은 경우에 설정됩니다.스크립트 출력(stdout)은 "Error"(대소문자 구분 없음)로 시작합니다.
이를 통해 클라이언트는 출력 텍스트를 구문 분석하지 않고도 실행이 실패했는지 쉽게 확인할 수 있습니다.
응답 예시(성공):
응답 예시(오류):
2. get_scripting_tips
서버의 지식 기반에서 AppleScript/JXA 팁, 예제 및 실행 가능한 스크립트 세부 정보를 가져옵니다. 사용 가능한 스크립트, 해당 기능, 그리고 execute_script (특히 kb_script_id )를 사용하여 스크립트 사용 방법을 찾는 데 유용합니다.
인수:
list_categories(부울, 선택 사항, 기본값: false): true인 경우, 사용 가능한 지식 기반 카테고리 목록과 해당 설명만 반환합니다. 다른 매개변수는 무시됩니다.category(문자열, 선택 사항): 특정 카테고리 ID(예: "finder", "safari")로 팁을 필터링합니다.search_term(문자열, 선택 사항): 팁 제목, 설명, 스크립트 내용, 키워드 또는 ID 내에서 키워드를 검색합니다.refresh_database(부울, 선택 사항, 기본값: false): true인 경우, 요청을 처리하기 전에 디스크에서 전체 지식 베이스를 강제로 다시 로드합니다. 개발 과정에서 지식 베이스 파일을 자주 수정하고 서버를 재시작하지 않고도 최신 버전을 사용하려는 경우 유용합니다.limit(정수, 선택 사항, 기본값: 10): 반환할 결과의 최대 개수.
산출:
요청된 팁, 즉 제목, 설명, 스크립트 내용, 언어, 실행 가능 ID(해당되는 경우), 인수 프롬프트 및 메모를 포함하는 마크다운 형식의 문자열을 반환합니다.
사용 예:
모든 카테고리 나열:
{ "toolName": "get_scripting_tips", "input": { "list_categories": true } }"safari" 카테고리에 대한 팁 받기:
{ "toolName": "get_scripting_tips", "input": { "category": "safari" } }"clipboard"와 관련된 팁을 검색하세요:
{ "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }
주요 사용 사례 및 예시
애플리케이션 제어:
Safari에서 현재 URL을 가져옵니다.
{ "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }Mail에서 읽지 않은 이메일의 제목 가져오기:
{ "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }
파일 시스템 작업:
바탕 화면에 있는 파일 나열:
{ "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }새 폴더를 만듭니다.
{ "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }
시스템 상호작용:
시스템 알림 표시:
{ "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }시스템 볼륨 설정:
{ "input": { "script_content": "set volume output volume 50" } }(0-100)현재 클립보드 내용 가져오기:
{ "input": { "script_content": "the clipboard" } }
문제 해결
권한 오류: 스크립트가 앱을 제어하거나 UI 작업을 수행하지 못하는 경우, MCP 서버를 실행하는 애플리케이션(예: 터미널)의 시스템 설정에서 자동화 및 접근성 권한을 다시 한 번 확인하세요.
스크립트 구문 오류:
osascript오류는stderr또는 오류 메시지로 반환됩니다. 복잡한 스크립트는 먼저 스크립트 편집기(AppleScript용) 또는 JXA 실행기를 사용하여 로컬에서 테스트하세요.시간 초과: 스크립트 실행 시간이
timeout_seconds(기본값 60초)보다 길어지면 스크립트가 종료됩니다. 장시간 실행되는 스크립트의 경우 시간 초과를 늘리세요.파일을 찾을 수 없습니다.
script_pathMCP 서버를 실행하는 사용자가 액세스할 수 있는 절대 POSIX 경로인지 확인하세요.잘못된 출력/JXA 문제: JXA 스크립트, 특히 Objective-C 브리징을 사용하는 스크립트의 경우,
output_format_mode가'direct'또는'auto'(기본값)로 설정되어 있는지 확인하세요. JXA에서human_readable과 같은 AppleScript 전용 포맷팅 플래그를 사용하면 오류가 발생할 수 있습니다. AppleScript 출력이 제대로 파싱되지 않으면structured_output_and_error또는structured_error사용해 보세요.
환경 변수를 통한 구성
LOG_LEVEL: 서버의 로깅 수준을 설정합니다.값:
DEBUG,INFO,WARN,ERROR예:
LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest
KB_PARSING: 지식 기반(스크립트 팁)이 구문 분석되는 시기를 제어합니다.가치:
lazy(기본값):get_scripting_tips에 대한 첫 번째 요청 또는execute_script에kb_script_id사용될 때 지식 기반이 파싱됩니다. 이를 통해 서버 시작 속도가 향상됩니다.eager: 지식 기반은 서버 시작 시 파싱됩니다. 이렇게 하면 시작 시간이 약간 길어질 수 있지만, 지식 기반을 즉시 사용할 수 있고 파싱 오류를 조기에 발견할 수 있습니다.
예(
start.sh또는 유사한 명령어를 통해 실행할 경우):KB_PARSING=eager ./start.sh예(
mcp-agentify와 같이env지원하는 MCP 러너를 통해 구성하는 경우):{ "env": { "LOG_LEVEL": "INFO", "KB_PARSING": "eager" } }
개발자를 위한
로컬 개발, 프로젝트 구조( knowledge_base 포함), 기여 지침에 대한 자세한 내용은 DEVELOPMENT.md를 참조하세요.
개발
프로젝트 구조, 빌드 및 테스트에 대한 자세한 내용은 DEVELOPMENT.md를 참조하세요.
지역 지식 기반
기본 지식 기반을 사용자 고유의 로컬 팁과 공유 핸들러로 보완할 수 있습니다. 이 저장소(또는 그 하위 집합)의 knowledge_base 과 동일한 디렉터리 구조를 생성하세요.
기본적으로 애플리케이션은 ~/.macos-automator/knowledge_base 에서 로컬 지식 베이스를 검색합니다. LOCAL_KB_PATH 환경 변수를 설정하여 이 경로를 사용자 지정할 수 있습니다.
예:
/Users/yourname/my-custom-kb 에 로컬 지식 베이스가 있다고 가정해 보겠습니다. 환경 변수를 다음과 같이 설정합니다. export LOCAL_KB_PATH=/Users/yourname/my-custom-kb
또는 검증 스크립트를 실행하는 경우 --local-kb-path 인수를 사용할 수 있습니다. npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb
구조 및 재정의:
로컬 지식 기반은 주요
knowledge_base(예:01_applescript_core,05_web_browsers/safari등)의 카테고리 구조를 반영해야 합니다.새로운
.md팁 파일이나_shared_handlers(예:.applescript또는.js파일)를 추가할 수 있습니다.로컬 지식 기반의 팁 ID(프론트매터
id:또는 파일 이름/경로에서 생성됨)가 내장된 지식 기반의 ID와 일치하는 경우, 로컬 버전이 내장된 버전을 재정의합니다 .마찬가지로, 로컬
_shared_handlers디렉토리에 있는 동일한 이름과 언어를 사용하는 공유 핸들러(예:my_utility.applescript)는 동일한 카테고리(또는 로컬 KB의_shared_handlers루트에 배치한 경우 전역적으로) 내에 있는 동일한 이름과 언어를 사용하는 모든 내장 핸들러를 재정의합니다.로컬 KB의
_category_info.md에 있는 카테고리 설명은 동일한 카테고리에 대한 내장 KB의 카테고리 설명을 재정의할 수도 있습니다.
이를 통해 핵심 애플리케이션 파일을 수정하지 않고도 사용 가능한 자동화 스크립트와 팁을 개인화하고 확장할 수 있습니다.
기여하다
기여를 환영합니다! 이슈와 풀 리퀘스트는 GitHub 저장소 에 제출해 주세요.
자동화 기능
이 서버는 AppleScript와 JavaScript for Automation(JXA)을 통해 강력한 macOS 자동화 기능을 제공합니다. 가장 유용한 몇 가지 예시는 다음과 같습니다.
터미널 자동화
새 터미널 탭에서 명령을 실행합니다.
{ "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }sudo로 명령을 실행하고 안전하게 비밀번호를 제공합니다.
처리를 위해 명령 출력을 캡처합니다.
브라우저 컨트롤
Chrome/Safari 자동화:
{ "input": { "kb_script_id": "chrome_open_url_new_tab_profile", "input_data": { "url": "https://example.com", "profile_name": "Default" } } }{ "input": { "kb_script_id": "safari_get_front_tab_url" } }브라우저 컨텍스트에서 JavaScript를 실행합니다.
{ "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }페이지 콘텐츠 추출, 양식 조작 및 워크플로 자동화
웹 페이지의 스크린샷을 찍으세요
시스템 상호 작용
시스템 설정(다크 모드, 볼륨, 네트워크)을 전환합니다.
{ "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }클립보드 내용 가져오기/설정:
{ "input": { "kb_script_id": "system_clipboard_get_file_paths" } }시스템 대화 상자 및 알림 열기/제어
시스템 알림 생성 및 관리
파일 작업
파일/폴더 생성, 이동 및 조작:
{ "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }텍스트 파일을 읽고 씁니다.
{ "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }디렉토리의 파일 나열 및 필터링
파일 메타데이터 및 속성 가져오기
애플리케이션 통합
캘린더/알림 관리:
{ "input": { "kb_script_id": "calendar_create_event", "input_data": { "title": "Meeting", "start_date": "2023-06-01 10:00", "end_date": "2023-06-01 11:00" } } }Mail.app을 사용한 이메일 자동화:
{ "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }음악 재생 제어:
{ "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }크리에이티브 앱(Keynote, Pages, Numbers)을 사용하여 작업하세요
get_scripting_tips 도구를 사용하면 범주별로 정리된 모든 사용 가능한 자동화 기능을 살펴볼 수 있습니다.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.