applescript-mcp MCP 서버
LLM 애플리케이션이 AppleScript를 통해 macOS와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(Model Context Protocol) 서버입니다. 이 서버는 AI 애플리케이션이 시스템 기능을 제어하고, 파일을 관리하고, 알림을 처리하는 등의 작업을 수행할 수 있는 표준화된 인터페이스를 제공합니다.
특징
🗓️ 캘린더 관리(이벤트, 알림)
📋 클립보드 작업
🔍 Finder 통합
🔔 시스템 알림
⚙️ 시스템 제어(볼륨, 다크 모드, 앱)
📟 iTerm 터미널 통합
📬 메일(새 이메일 만들기, 이메일 목록, 이메일 받기)
🔄 단축키 자동화
💬 메시지(채팅 목록, 메시지 받기, 메시지 검색, 메시지 보내기)
🗒️ 노트(서식 있는 노트 만들기, 노트 목록 만들기, 노트 검색)
📄 페이지(문서 생성)
계획된 기능
Related MCP server: MCP-AppleMusic
필수 조건
macOS 10.15 이상
Node.js 18 이상
사용 가능한 카테고리
달력
명령 | 설명 | 매개변수 |
add
| 캘린더 이벤트 만들기 | title
, startDate
, endDate
, calendar
(선택 사항) |
list
| 오늘의 이벤트를 나열하세요 | 없음 |
예시
지엑스피1
클립보드
명령 | 설명 | 매개변수 |
set_clipboard
| 클립보드에 복사 | content
|
get_clipboard
| 클립보드 내용 가져오기 | 없음 |
clear_clipboard
| 클립보드 지우기 | 없음 |
예시
// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard
// Get clipboard contents
What's currently in my clipboard?
// Clear clipboard
Clear my clipboard
파인더
명령 | 설명 | 매개변수 |
get_selected_files
| 선택한 파일 가져오기 | 없음 |
search_files
| 파일 검색 | query
, location
(선택 사항) |
quick_look
| 미리보기 파일 | path
|
예시
// Get selected files in Finder
What files do I currently have selected in Finder?
// Search for files
Find all PDF files in my Documents folder
// Preview a file
Show me a preview of ~/Documents/report.pdf
알림
참고: 알림을 보내려면 시스템 설정 > 알림 > 스크립트 편집기에서 알림을 활성화해야 합니다.
명령 | 설명 | 매개변수 |
send_notification
| 알림 표시 | title
, message
, sound
(선택 사항) |
toggle_do_not_disturb
| DND 모드 전환 | 없음 |
예시
// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"
// Toggle Do Not Disturb
Turn on Do Not Disturb mode
체계
명령 | 설명 | 매개변수 |
volume
| 시스템 볼륨 설정 | level
(0-100) |
get_frontmost_app
| 활성화된 앱을 받으세요 | 없음 |
launch_app
| 오픈 애플리케이션 | name
|
quit_app
| 응용 프로그램 닫기 | name
, force
(선택 사항) |
toggle_dark_mode
| 다크 모드 전환 | 없음 |
예시
// Set system volume
Set my Mac's volume to 50%
// Get active application
What app am I currently using?
// Launch an application
Open Safari
// Quit an application
Close Spotify
// Toggle dark mode
Switch to dark mode
아이텀
명령 | 설명 | 매개변수 |
paste_clipboard
| iTerm에 붙여넣기 | 없음 |
run
| 명령 실행 | command
, newWindow
(선택 사항) |
예시
// Paste clipboard to iTerm
Paste my clipboard contents into iTerm
// Run a command in iTerm
Run "ls -la" in iTerm
// Run a command in a new iTerm window
Run "top" in a new iTerm window
단축키
명령 | 설명 | 매개변수 |
run_shortcut
| 바로가기 실행 | name
, input
(선택 사항) |
list_shortcuts
| 사용 가능한 모든 단축키 나열 | limit
(선택 사항) |
예시
// List available shortcuts
List all my available shortcuts
// List with limit
Show me my top 5 shortcuts
// Run a shortcut
Run my "Daily Note in Bear" shortcut
// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"
우편
명령 | 설명 | 매개변수 |
create_email
| Mail.app에서 새 이메일을 만드세요 | recipient
, subject
, body
|
list_emails
| 사서함에서 이메일 나열 | mailbox
(선택 사항), count
(선택 사항), unreadOnly
(선택 사항) |
get_email
| 검색을 통해 특정 이메일 받기 | subject
(선택 사항), sender
(선택 사항), dateReceived
(선택 사항), mailbox
(선택 사항), account
(선택 사항), unreadOnly
(선택 사항), includeBody
(선택 사항) |
예시
// Create a new email
Compose an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"
// List emails
Show me my 10 most recent unread emails
// Get a specific email
Find the email from sarah@example.com about "Project Update"
메시지
명령 | 설명 | 매개변수 |
list_chats
| 사용 가능한 iMessage 및 SMS 채팅 나열 | includeParticipantDetails
(선택 사항, 기본값: false) |
get_messages
| 메시지 앱에서 메시지 받기 | limit
(선택 사항, 기본값: 100) |
search_messages
| 특정 텍스트가 포함된 메시지 검색 | searchText
, sender
(선택 사항), chatId
(선택 사항), limit
(선택 사항, 기본값: 50), daysBack
(선택 사항, 기본값: 30) |
compose_message
| 미리 채워진 메시지 또는 자동 전송으로 메시지 앱을 엽니다. | recipient
(필수), body
(선택), auto
(선택, 기본값: false) |
예시
// List available chats
Show me my recent message conversations
// Get recent messages
Show me my last 20 messages
// Search messages
Find messages containing "dinner plans" from John in the last week
// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"
노트
명령 | 설명 | 매개변수 |
create
| 마크다운과 유사한 서식으로 메모 만들기 | title
, content
, format
(서식 옵션이 있는 경우 선택 사항) |
createRawHtml
| 직접 HTML 콘텐츠로 메모 만들기 | title
, html
|
list
| 특정 폴더에서 선택적으로 메모를 나열합니다. | folder
(선택 사항) |
get
| 제목으로 특정 메모 받기 | title
, folder
(선택 사항) |
search
| 특정 텍스트가 포함된 노트 검색 | query
, folder
(선택 사항), limit
(선택 사항, 기본값: 5), includeBody
(선택 사항, 기본값: true) |
예시
// Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists
// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"
// List notes
Show me all my notes in the "Work" folder
// Get a specific note
Show me my note titled "Shopping List"
// Search notes
Find notes containing "recipe" in my "Cooking" folder
페이지
명령 | 설명 | 매개변수 |
create_document
| 일반 텍스트로 새 Pages 문서 만들기 | content
|
예시
// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."
건축학
AppleScript-MCP 서버는 TypeScript를 사용하여 구축되었으며 모듈식 아키텍처를 따릅니다.
핵심 구성 요소
AppleScriptFramework ( framework.ts ): 다음을 수행하는 주요 서버 클래스:
MCP 프로토콜 통신을 관리합니다
도구 등록 및 실행을 처리합니다.
로깅 기능을 제공합니다
AppleScript 명령을 실행합니다
카테고리 ( src/categories/*.ts ): 기능별로 구성된 모듈식 스크립트 컬렉션:
각 카테고리에는 관련 스크립트(예: 달력, 시스템, 메모)가 포함되어 있습니다.
카테고리는 index.ts 의 프레임워크에 등록됩니다.
유형 ( src/types/index.ts ): 다음을 정의하는 TypeScript 인터페이스:
실행 흐름
클라이언트는 MCP 프로토콜을 통해 도구 요청을 보냅니다.
서버는 적절한 카테고리와 스크립트를 식별합니다.
스크립트 콘텐츠가 생성됩니다(정적 또는 함수를 통한 동적으로)
AppleScript는 macOS osascript 명령을 통해 실행됩니다.
결과는 클라이언트에게 반환됩니다.
로깅 시스템
프레임워크에는 다음과 같은 포괄적인 로깅 시스템이 포함되어 있습니다.
stderr 및 MCP 로깅 프로토콜 모두에 기록합니다.
다양한 심각도 수준(디버그, 정보, 경고, 오류 등)을 지원합니다.
문제 해결을 위한 자세한 실행 정보를 제공합니다.
개발
설정
# Install dependencies
npm install
# Build the server
npm run build
# Launch MCP Inspector
# See: https://modelcontextprotocol.io/docs/tools/inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...
새로운 기능 추가
1. 카테고리 파일 생성
src/categories/newcategory.ts 생성합니다.
import { ScriptCategory } from "../types/index.js";
export const newCategory: ScriptCategory = {
name: "category_name",
description: "Category description",
scripts: [
// Scripts will go here
],
};
2. 스크립트 추가
{
name: "script_name",
description: "What the script does",
schema: {
type: "object",
properties: {
paramName: {
type: "string",
description: "Parameter description"
}
},
required: ["paramName"]
},
script: (args) => `
tell application "App"
// AppleScript code using ${args.paramName}
end tell
`
}
3. 카테고리 등록
src/index.ts 업데이트:
import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);
고급 스크립트 개발
더 복잡한 스크립트의 경우 다음을 수행할 수 있습니다.
동적 스크립트 생성을 사용하세요 :
script: (args) => {
// Process arguments and build script dynamically
let scriptContent = `tell application "App"\n`;
if (args.condition) {
scriptContent += ` // Conditional logic\n`;
}
scriptContent += `end tell`;
return scriptContent;
}
복잡한 데이터 처리 :
// Example from Notes category
function generateNoteHtml(args: any): string {
// Process markdown-like syntax into HTML
let processedContent = content;
if (format.headings) {
processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
// ...
}
return processedContent;
}
디버깅
MCP Inspector 사용
MCP Inspector는 서버를 테스트하고 디버깅하기 위한 웹 인터페이스를 제공합니다.
벌채 반출
환경 변수를 설정하여 디버그 로깅을 활성화합니다.
DEBUG=applescript-mcp* npm start
구성 예
npm run build 실행한 후 mcp.json 파일에 다음을 추가합니다.
{
"mcpServers": {
"applescript-mcp-server": {
"command": "node",
"args": ["/path/to/applescript-mcp/dist/index.js"]
}
}
}
일반적인 문제
권한 오류 : 시스템 환경 설정 > 보안 및 개인 정보 보호 > 개인 정보 보호 > 자동화 확인
스크립트 실패 : 통합하기 전에 Script Editor.app에서 직접 스크립트를 테스트합니다.
통신 문제 : stdio 스트림이 리디렉션되지 않는지 확인하세요.
데이터베이스 액세스 : 일부 기능(예: 메시지)에는 전체 디스크 액세스 권한이 필요합니다.
자원
기여하다
저장소를 포크하세요
기능 브랜치 생성
변경 사항을 커밋하세요
지점으로 밀어 넣기
풀 리퀘스트 만들기
특허
MIT 라이선스 - 자세한 내용은 라이선스를 참조하세요.