macos-mcp

macOS에서 AI 에이전트 또는 셸에서 Reminders, Calendar, Notes, Mail, Messages, Contacts를 제어합니다.

Apple은 이 앱들에 대해 세 가지 자동화 표면을 제공하지만, 각각은 어딘가에서 실패합니다. EventKit은 Notes, Mail, Messages, Contacts에 접근하지 못합니다. JXA로 Messages를 읽으면 Sonoma 이상에서 아무것도 반환되지 않습니다. JXA로 Mail을 읽으면 실제 받은 편지함에서 60초에 타임아웃됩니다. 이 프로젝트는 앱별로 작동하는 브리지를 사용하며, 그 이유는 DECISION.md에 문서화되어 있습니다.

Mac이 필요합니다. 이 브리지들은 EventKit, Apple Events, 그리고 로컬 Apple 데이터베이스의 SQLite 읽기입니다. Linux, Windows, iOS, Android 또는 브라우저 빌드는 없습니다.

세 가지 사용 방법

MCP 서버로. 로컬 stdio 전송을 사용하며, 같은 Mac의 모든 MCP 지원 클라이언트(Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT 데스크톱)에서 작동합니다. 8개의 도구가 있으며, 도구 아래에 나열되어 있습니다.

에이전트 스킬로. 동일한 브리지를 셸 명령으로 호출하며, 컨텍스트에 도구 스키마가 로드되지 않습니다. MCP 서버는 세션이 Mac 앱을 건드리지 않더라도 세션 시작 시 8개의 도구 정의를 모두 모델 앞에 배치합니다. 스킬은 트리거가 발생할 때까지 설명 한 줄에 불과합니다. 스킬은 skills/macos/에서, 선택 방법은 docs/mcp-vs-skill.md에서 확인하세요.

CLI로. EventKitCLI는 stdout에 JSON을 출력하는 독립형 Swift 바이너리입니다. 스킬의 JXA 및 SQLite 레시피는 셸이 있는 곳이라면 어디서든 실행됩니다.

Related MCP server: Apple MCP

빠른 시작

Claude Code 플러그인으로 설치

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

Claude Code 내에서 실행하세요. 플러그인은 npx -y mcp-macos를 통해 MCP 서버를 연결하므로 별도의 설치 단계가 필요하지 않습니다.

npm에서 설치

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

또는 MCPB(Claude Desktop)로 설치

최신 GitHub 릴리스에서 .mcpb 번들을 다운로드하여 Claude Desktop에 끌어다 놓으세요. 번들에는 사전 빌드된 유니버설 Swift 바이너리(arm64 + x86_64)가 포함되어 있어 Xcode Command Line Tools가 필요하지 않습니다.

또는 소스에서 빌드

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

설정 확인

macos-mcp --check   # or: node dist/index.js --check

macOS 버전, Node.js, EventKit 바이너리, Full Disk Access, JXA 자동화 권한을 확인합니다.

또는 서버 대신 스킬로 사용

스킬을 에이전트의 스킬 디렉터리에 복사하세요. MCP 서버도, 컨텍스트의 도구 스키마도 필요 없습니다.

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

스킬은 EventKitCLI, osascript, sqlite3을 직접 호출하므로 Swift 바이너리가 PATH에 있어야 합니다:

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

어느 쪽이든 동일한 권한이 적용됩니다. 권한을 참조하세요.

도구

밑줄(reminders_tasks)과 점(reminders.tasks) 표기법 모두 작동합니다.

설계 노트

• 읽기는 SQLite, 쓰기는 JXA. JXA로 Mail을 읽는 것은 확장이 불가능하여 실제 받은 편지함에서 60초 타임아웃이 발생하고, JXA로 Messages를 읽는 것은 macOS Sonoma 이상에서 완전히 깨져 있습니다. 이 프로젝트는 chat.db와 Mail의 Envelope Index를 직접 읽으며, [Gmail]/All Mail 계정의 Gmail labels 조인 테이블도 포함합니다. 쓰기는 여전히 JXA를 통해 이루어지는데, Apple Events가 이를 트리거하는 유일한 API이기 때문입니다. ADR-001을 참조하세요.

• 앱별 하이브리드 백엔드. 각 앱은 작동하는 브리지를 사용합니다: Reminders와 Calendar는 EventKit을 통한 Swift CLI, Notes, Contacts, Mail 쓰기와 Messages 전송은 JXA, Mail과 Messages 읽기는 SQLite입니다. 아키텍처 다이어그램에 팬아웃이 나와 있습니다.

• 도구 간 연락처 강화. 공유 레이어가 Messages, Mail, Calendar 전반에서 원시 전화번호와 이메일 주소를 연락처 이름으로 해석합니다. SQLite AddressBook 저장소를 통한 대량 캐시는 1,100개 항목에 대해 50ms 미만이며, JXA whose()를 통한 대상 조회도 지원합니다. ADR-002를 참조하세요.

• 사전 점검. macos-mcp --check는 런타임 전에 macOS 버전, Node.js, EventKit 바이너리, Full Disk Access, JXA 권한을 검증하고, 실패한 항목에 대해 관련 시스템 설정 창으로의 딥 링크를 제공합니다.

설정

사전 요구 사항

• Node.js 20+

• macOS

• Xcode Command Line Tools (Swift 컴파일)

클라이언트 구성

JSON 구성은 모든 클라이언트에서 동일합니다. 위치만 다릅니다.

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

권한

macOS는 첫 사용 시 접근을 요청합니다. 메시지가 표시되면 허용을 클릭하세요.

Messages와 Mail은 SQLite 데이터베이스를 직접 읽으므로 터미널 앱(Terminal, iTerm2 등)에 전체 디스크 접근 권한이 필요합니다.

macos-mcp --check를 실행하여 확인하세요. 실패하는 항목이 있으면 문제 해결을 참조하세요.

문제 해결

빠른 수정 명령

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

전체 디스크 접근 (Messages 및 Mail)

Messages와 Mail은 SQLite 데이터베이스(~/Library/Messages/chat.db 및 ~/Library/Mail/V10/MailData/Envelope Index)를 읽습니다. 터미널 앱에 전체 디스크 접근 권한이 필요합니다.

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

버전 관리자 사용자(Volta, nvm, fnm): node 명령은 심(shim)입니다. 시스템 설정에는 실제 바이너리가 필요합니다:

시스템 설정은 숨김 디렉터리의 바이너리를 표시하지 않을 수 있습니다. 위의 open -R을 사용하여 Finder에서 표시한 후 FDA 목록으로 끌어다 놓으세요.

JXA 자동화 (Notes, Mail, Contacts)

첫 사용 시 macOS가 자동화 접근을 요청합니다. 시스템 설정 > 개인정보 보호 및 보안 > 자동화에서 허용하세요.

권한 확인:

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

각 명령은 값을 반환해야 합니다. 멈춤은 권한 대화상자가 표시되려고 시도(하고 실패)하고 있음을 의미합니다.

Gmail 라벨 / 받은 편지함 메시지 누락

Gmail은 모든 메시지를 [Gmail]/All Mail에 저장하고 라벨을 사용하여 폴더 구성을 처리합니다. 서버는 직접 사서함과 라벨 조인 테이블을 모두 확인합니다. Gmail 받은 편지함 메시지가 누락된 경우 Mail 앱이 완전히 동기화되었는지 확인하세요.

개발

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

프로덕션 진입점(bin/run.cjs)은 pnpm build가 필요합니다. 로컬 개발에는 pnpm dev를 사용하세요.

아키텍처

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

Apple 앱에 대한 세 가지 브리지:

• EventKit (Swift 바이너리). Reminders, Calendar. 컴파일된 Swift CLI로 JSON을 반환합니다.

• JXA. Notes, Mail 쓰기, Contacts. osascript -l JavaScript를 통해 실행되는 스크립트.

• SQLite. Messages 읽기(~/Library/Messages/chat.db), Mail 읽기(~/Library/Mail/V10/MailData/Envelope Index). JXA 메시지 읽기는 Sonoma 이상에서 깨져 있습니다. JXA 메일 읽기는 실제 받은 편지함에 너무 느립니다.

Mail과 Messages는 하이브리드 경로를 사용합니다: 쓰기는 JXA(보내기/임시보관을 트리거하는 유일한 방법), 읽기는 SQLite(확장이 가능한 유일한 방법)입니다. 아키텍처 결정 기록은 DECISION.md를 참조하세요.

의존성

런타임: @modelcontextprotocol/sdk, zod

개발: typescript, tsx, jest, @biomejs/biome

크레딧

MCP 서버 레이어는 FradSer/mcp-server-apple-events(MIT)에서 시작되었습니다. EventKit Swift CLI, SQLite 읽기 경로, 연락처 강화, 사전 점검, 스킬 표면은 여기에서 추가되었습니다.

라이선스

MIT

기여

CONTRIBUTING.md를 참조하세요.