Cupertino

여러분의 에이전트를 일상적인 Apple 앱에서 활용하세요.

이미 Mac에 있는 Apple 앱들을 위한 MCP 서버와, 그 권한을 호스트마다 한 번씩이 아니라 한 번만 부여하는 서명된 앱 — 특정 호스트가 아닌, MCP를 말하는 모든 에이전트를 위한 것입니다.

비공식. Apple과 무관합니다. 이는 이미 Mac에 있는 앱들을 구동합니다.

사용 예시

업무용 받은 편지함에서 내가 쓰는 문체를 보고, 같은 톤으로 이 답장을 초안 작성해 줘.

메일, 메모, 캘린더에서 Atlas 출시에 관한 모든 것을 모아 줘. 내가 아직 사람들에게 빚진 게 뭐지?

어제 고객 스레드의 실행 항목들을 금요일 마감으로 알림으로 바꿔 줘.

이 모든 것에는 제약 조건 — 계정, 날짜 범위, 필터 — 이 담겨 있습니다. 이것이 순진한 osascript 방식이 74초가 걸리거나 틀리게 답하는 부분이며, 서버가 존재할 자격이 있는 이유입니다: 모델이 매 세션마다 다시 유도해야 할 것을 서버가 보유하고 있기 때문입니다. 측정값은 docs/verify.md에, 대안들의 비용은 docs/alternatives.md에 있습니다.

마지막 예시는 Reminders의 쓰기 게이트가 열려 있어야 합니다. 쓰기는 각 표면별로 기본적으로 꺼져 있으며, 사용자가 켜기 전까지는 꺼져 있습니다. 그리고 이 토글은 변경 도구가 등록되는지 여부를 결정합니다 — 쓰기가 꺼진 에이전트는 그 도구들이 존재하는지조차 볼 수 없습니다.

Related MCP server: apple-mcp

표면

각 표면은 자체 서버이자 자체 npm 패키지이므로, 호스트는 원하는 도구만 로드합니다. 이들은 하나의 번들과 하나의 Full Disk Access 권한을 공유하며, 이것이 함께 존재하는 이유입니다 — docs/distribution.md 참조.

빠른 시작

각 서버는 npm에 있으며 npx로 바로 실행됩니다 — Claude Code의 경우, 프로젝트 옆에 .mcp.json을 두면 됩니다:

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-mail"]
    },
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-notes"]
    }
  }
}

패키지들은 MIT 라이선스이며 라이선스 키가 필요 없습니다. 필요한 것은 권한이며, npm에서는 이를 실행하는 프로세스 — 편집기, 터미널 — 에 부여하게 됩니다. 이것이 서명된 Cupertino.app이 존재하는 이유입니다: 호스트마다 하나씩이 아니라, 공증된 바이너리가 보유하는 하나의 Full Disk Access 권한. docs/licensing.md 참조.

또는 소스에서 실행:

git clone https://github.com/mgcrea/mcp-cupertino.git
cd mcp-cupertino
pnpm install
pnpm build

그런 다음 호스트를 packages/<surface>/dist/cli.js의 절대 경로로 지정하세요.

쓰기는 요청하지 않는 한 꺼져 있습니다 — 구성 참조.

메뉴 바 앱을 통해 실행하면 모든 서버가 브리지를 거치므로, Full Disk Access가 서버를 실행한 편집기가 아니라 Cupertino에 부여됩니다:

make run      # build Cupertino.app, point it at packages/*/dist, launch it
make smoke    # handshake every server through the bridge

저장소에 체크인된 .mcp.json은 해당 경로로 연결되어 있습니다. make만 실행하면 모든 대상을 나열합니다.

서버 이름이 다르다는 점에 주의하세요. 위와 같이 수동으로 연결하면 서버는 apple-mail이며 호스트 프로세스가 가진 권한으로 실행됩니다. Cupertino로 연결하면 cupertino-mail인데, 해당 항목이 앱의 브리지를 가리키고 앱의 권한으로 실행되기 때문입니다. 두 배포 방식에 두 이름이 있으며, 둘 다 가질 수 있습니다. 앱은 자신의 cupertino-* 키만 건드립니다 — 다른 서버에 속한 apple-mail 항목은 그대로 둡니다.

Cupertino는 프로젝트 의존성이 아니라 시스템 구성이므로 사용자별 구성에 들어갑니다: Claude Desktop, Cursor, LM Studio, Windsurf 각각에 파일 하나씩, 그리고 CLI에는 --scope user — 앱의 복사 가능한 명령이 사용하는 방식입니다. 의도적으로 --scope project는 아닙니다. 이는 커밋되도록 만들어진 .mcp.json을 작성하는데, 해당 항목은 한 Mac의 번들에 대한 절대 경로이며 한 사람의 Full Disk Access 권한에 기반하므로 팀원에게는 쓸모없고 제공하기에도 현명하지 않습니다.

어떤 클라이언트가 파일을 받고 어떤 클라이언트가 명령을 받는지는 인기와 무관합니다. 앱은 mcpServers 아래에 서버가 있는 엄격한 JSON일 때만 구성에 병합합니다. Visual Studio Code는 JSONC이고 Codex는 TOML이며, 둘 중 하나를 다시 직렬화하면 수동으로 유지 관리되는 파일의 주석이 삭제됩니다. Claude Code의 ~/.claude.json은 엄격한 JSON이지만 자격 증명을 보유하고 실행 중인 세션이 동시에 기록하므로, 메뉴 바의 읽기-수정-쓰기가 다른 사람의 변경 사항을 놓칠 수 있습니다. 이 세 가지는 붙여넣을 명령을 받습니다. ChatGPT는 완전히 제외됩니다: 원격 HTTP 커넥터만 받으며 로컬 stdio 서버를 실행할 수 없습니다.

이 저장소 자체의 .mcp.json은 예외이며, 의도적으로 서버 이름을 cupertino-*-dev로 지정합니다: apps/apple/.build를 가리키므로 앱 작업 시 개발 빌드와 설치된 빌드를 나란히 두는 것을 의미합니다. Claude Code는 두 범위에서 같은 이름의 서버를 선택하는 대신 충돌로 보고하므로, 접미사가 둘 다 사용 가능하게 유지하는 것입니다.

Cupertino.app은 macOS 26 이상이 필요합니다 — 아이콘이 Icon Composer 번들이며, 그 이전 버전은 렌더링할 수 없습니다. 서버 자체는 일반 Node이며 그러한 제한이 없습니다. 메뉴 바 앱만 그렇습니다.

권한

두 가지 별도의 macOS 권한이며, 이는 서버를 실행한 프로세스 — 편집기, 터미널 또는 Cupertino — 에 부여되며, Mail, Notes 또는 Reminders 자체에는 절대 부여되지 않습니다.

시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한 → 실행 앱을 추가한 후 다시 시작하세요. Mail.app에 부여하는 것은 아무 효과가 없습니다. 권한이 필요한 것은 Mail이 아니라 읽는 쪽입니다.

Full Disk Access 없이 작동하는 것:

인덱스가 필요한 도구는 인덱스가 없어도 사라지지 않습니다 — 도구 목록은 allowWrites와 그 외 아무것도 없는 순수 함수입니다. MCP 클라이언트가 이를 캐시하기 때문입니다. 대신 무엇이 없는지 명명하는 구조화된 degraded 결과를 반환합니다. apple_mail_diagnostics / apple_notes_diagnostics는 어떤 경로가 활성 상태인지와 누락된 권한을 부여하는 방법을 보고합니다.

도구

읽기 도구는 항상 등록됩니다. 쓰기 도구는 쓰기가 활성화되지 않으면 보이지 않습니다 — 단순히 거부되는 것이 아닙니다.

Mail

Notes

Reminders

Calendar

list_events는 반복 이벤트를 확장하므로, 주간 스탠드업은 주당 한 번씩 반환됩니다. 모든 결과에는 확장 결과가 알려진 기간이 포함되며, 범위를 지나치는 검색은 결과가 부족해지지 않도록 truncated를 설정합니다. 이벤트 목록이 짧은 것은 빈 오후와 구별할 수 없기 때문입니다.

Contacts

resolve_handles는 전화번호와 이메일 주소를 이름으로 변환하며, 이것이 Messages 표면을 읽을 수 있게 만드는 핵심입니다. 각 결과의 status를 읽어서 이름이 반환되었다고 가정하지 마십시오. unknown 은 흔하며 오류가 아니고, ambiguous는 두 연락처가 번호를 공유한다는 뜻이므로 추측을 반환하는 대신 이름을 반환하지 않습니다.

삭제 도구는 없습니다. Contacts의 스크립팅 사전에는 어떤 종류의 삭제 명령도 없으며, 여기서 모든 표면의 쓰기는 Apple Events를 통해 이루어집니다. 저장소는 정책상 읽기 전용이기 때문입니다. docs/contacts.md를 참조하세요.

Messages

사용 가능한 쓰기 명령이 사전에 하나뿐이므로 쓰기 도구도 하나입니다. sdef는 send, login, logout을 나열하며, 나머지 두 명령은 이용자가 소유한 모든 기기에서 iMessage를 로그아웃시킬 것입니다. 노출할 편집, 삭제, 읽음 표시 또는 반응 동사는 없습니다.

이 표면은 Apple Events가 쓰기 레인일 뿐인 유일한 곳입니다. 이 경로로는 모든 읽기가 실패하므로 APPLE_MESSAGES_ALLOW_WRITES가 꺼져 있으면 Apple Event는 전혀 전송되지 않고 Automation 권한도 요청되지 않습니다.

send_message는 원시 핸들보다 list_chats의 chatRef를 선호합니다. Messages가 스크립트에 참가자를 열거하지 않기 때문입니다. 기존 대화만 안정적으로 주소를 지정할 수 있는 유일한 대상입니다. Apple Events는 보낸 것에 대한 식별자를 돌려주지 않으므로 결과는 chat.db와 대조하여 조정됩니다. reconciliation: "매칭됨"은 실제 메시지 참조를 가지며, "pending"은 Messages가 전송을 수락했지만 아직 로우를 쓰지 않았다는 뜻입니다. Pending은 실패가 아니며, 재시도하면 메시지가 두 번 전송됩니다.

전체 기록 중 약 3%의 메시지는 텍스트가 SQL로 접근할 수 없는 아카이브된 NSArchiver blob에만 보존되어 있습니다. Apple은 2026년 초에 일반 텍스트 열 작성을 중단했으므로 최근 항목은 ~100%가 그렇습니다. 이 서버가 이를 디코딩하며, 모든 결과의 textSource는 어느 경로가 응답했는지 알려줍니다. docs/messages.md를 참조하세요.

Safari

읽기 전용이며, 쓰기 열은 의도적으로 비어 있습니다. URL을 열거나 읽기 목록에 추가하는 것은 실제 보이는 브라우저를 조운 Apple Event이며, 이 표면에서 쓰기를 시도한 적은 없습니다.

list_tabs는 전체 번들에서 Full Disk Access 없이 동작하는 유일한 도구입니다. 대신 Automation 권한이 필요하며 Safari가 실행 중이어야 합니다. 탭의 history 필드가 null이면 기록에서 찾을 수 없음을 의미하며, "never visited"가 아닙니다. 열린 탭 중 약 55%만이 기록 행과 일치하는데, 리디렉트, 세션 매개변수, 기록에 커밋된 전 없다가 발견된 페이지가 모두가 약자지 않은 URL을 만들기 때문입니다.

do JavaScript 도구는 없습니다. 이 동산은 "Allow JavaScript from Apple Events"라는 Safari 개발자 메뉴 설정이 필요하며, 이 설정은 TCC 권한이 아니고 그 자체의 상태를 신뢰성 있게 읽을 수도 없습니다. 이를 배포하면 표면이 정상이라 보고하면서 가장 강력한 기능은 조용히 실패하는 셈입니다. docs/safari.md를 참조하세요.

모든 이름은 apple_mail_ / apple_notes_ / apple_reminders_ / apple_calendar_ / apple_contacts_ / apple_messages_ / apple_safari_ 접두사로 지정됩니다.

구성

환경 변수만 사용합니다 — 이 서버들은 자체적으로 그 어떤 비밀도 저장하지 않으므로 설정 파일이 없습니다. 접두사는 APPLE_MAIL_, APPLE_NOTES_, APPLE_REMINDERS_, APPLE_CALENDAR_, APPLE_CONTACTS_, APPLE_MESSAGES_ 또는 APPLE_SAFARI_입니다.

allowWrites는 쓰기를 게이트 하지만, Mail에서 더 큰 위험 반경은 전체 아카이브를 읽는 것입니다. *_ACCOUNTS가 바로 그 용도이며, 정확히 한 곳에서 강제 적용되어 어떤 쿼리 경로도 이 제한을 벗어날 수 없습니다. Mail은 또한 *_ROOT, *_ENVELOPE_INDEX, *_DEGRADED_MAX_MESSAGES, *_BODY_MAX_BYTES, *_BODY_SCAN_MAX, *_BODY_SCAN_BYTES, *_MAILBOX_CACHE_TTL_MS을 사용합니다. packages/mail/src/config.ts를 참조하세요.

앱

메뉴 막대가 Cupertino의 전체 화면입니다. Dock 아이콘도 기본 창도 없습니다.

Activity 창은 도구 이름만 기록합니다 — 인자, 메시지 내용, 결과는 절대 기록하지 않습니다. 이것은 "어시스턴트가 방금 내 메일로 무엇을 했는가"에 대한 답이며, 서버를 스폰한 에디터 내부가 아니라 사용자가 볼 수 있는 앱 아래에서 실행하는 이유입니다.

쓰기는 표면별로 끄고 켜야만 사용할 수 있으며, 토글에 의해 변형 도구가 등록되는지 자체가 결정됩니다. 쓰기가 꺼지면 어느 어시스턴트도 그 도구가 존재한다는 것을 알지 못합니다.

하나의 앱인 이유

Full Disk Access 는 분할할 수 없는 전체 디스크 권한입니다. 표면마다 이 권한을 부여하면 격리 효과는 없고 그때마다 System Settings를 방문하게 됩니다. 그래서 열거한 모든 표면은 Cupertino라는 하나의 서명되고 앱 입니다. docs/distribution.md는 Mac App Store도 이 중 어떤 표면도 호스팅할 수 없는 이유를 기록해, 이후 같은 질문을 다시 열지 않도록 합니다.

하지만 권한 부여가 앱이 보유하는 유일한 것은 아니며, 서버를 에디터 대신 이 앱 아래 실행해야 하는 이유도 그 권한 하나만 있는 것이 아닙니다.

docs/alternatives.md는 그 목록의 솔직한 버전입니다. 어시스턴트를 위해 Apple Mail을 읽는 다른 도구나, 이 도구들이 앞선 곳을 다룹니다.

문서

작업 중

pnpm build          # every package
pnpm test           # every package
pnpm typecheck
pnpm lint
pnpm format

마케팅 사이트는 별도의 워크스페이스이며 수동으로 배포됩니다:

pnpm --filter @mgcrea/cupertino-website dev     # astro dev
pnpm --filter @mgcrea/cupertino-website build   # static build

.idea/design/의 디자인 캔버스에서 빌드되며, 도구 수는 이 파일이 아니라 packages/*/src/tools/에서 읽어옵니다 — apps/website를 참조하세요.

Swift 절반은 xcodebuild이며, Makefile이 이를 감싸지 않고 이름 그대로 호출합니다:

make app            # build Cupertino.app (Debug)
make run            # build, point at packages/*/dist, launch
make smoke          # handshake every server through the bridge
make stop           # quit and remove the socket

앱 스크린샷은 손으로 찍지 않고 캡처됩니다 — apps/apple/Screenshots/에 구성과 커밋된 골든 파일이 들어 있고, 웹사이트가 출력을 렌더링합니다:

make screenshots          # capture, gate against the goldens, compose both sets
make screenshots-check     # gate only — fails if the UI drifted
make screenshots-update    # accept the captures as the new goldens (review the diffs first)
make screenshots-selftest  # prove the gate fails when it should

실행 중에는 각 촬영 순간에 포인터와 활성 앱을 제어하므로, 실행하는 동안 컴퓨터를 사용하지 마세요. 터미널에 Screen Recording 권한이 필요하며, Cupertino 자체에는 필요하지 않습니다. make screenshots-doctor는 이 권한과, 그렇지 않으면 조용히 실패하는 두 가지(캡션 글꼴이 확인되는지, 출력 크기가 스토어에서 허용할 크기인지)를 확인합니다.

스크린샷이 보여주는 것은 이 Mac이 아니라 apps/apple/Cupertino/DemoSeed.swift의 픽스처 데이터입니다. -ScreenshotMode에서 앱은 호스트를 시작하지 않고 자체 로그와 세션을 시드하며, 권한 및 스토어 질문에 테이블로 답합니다. 그렇게 하지 않으면 이미지에 한 노트북의 TCC 상태가 기록되고 홈 디렉터리가 마케팅 사이트에 출력될 것입니다.

Phase-0 프로브는 리포지토리 전체를 대상으로 하며 읽기 전용입니다. 측정하는 표면의 권한이 필요하며, 출력을 개수, 타이밍, DDL로 편집합니다:

pnpm probe:mail      # Envelope Index — needs Full Disk Access
pnpm probe:mail-body # which lane can search message bodies — needs Full Disk Access
pnpm probe:notes     # Notes — the Apple Events half runs without it
pnpm probe:reminders # Reminders — the store path is a glob, so finding it is itself privileged
pnpm probe:messages  # chat.db — no Apple Events read lane exists, so this one needs the grant
                     #   --send-target=<handle> also checks the send lane's targeting, without sending
pnpm probe:calendar  # settles whether Calendar has a file lane at all
pnpm probe:safari    # History.db, and the Reading List hiding inside Bookmarks.plist
pnpm probe:contacts  # the resolver Messages needs — its own TCC grant, not Full Disk Access

이제 모든 프로브 대상 표면에는 패키지가 있습니다. Safari는 읽기 전용입니다 — 변경 도구를 등록하지 않으며, 이는 누락이 아니라 기록된 결정입니다. URL을 열거나 Reading List에 추가하면 실제로 보이는 브라우저를 탐색하게 되므로 프로브된 적이 없습니다. docs/safari.md를 참조하세요. Messages는 정확히 하나의 쓰기 도구인 send_message만 등록하며, 이것이 스크립팅 사전이 할 수 있는 전부입니다. 모든 프로브는 종료하는 대신 저하됩니다 — 실행 중이 아닌 앱이나 부여되지 않은 권한은 결과로 보고되며 — --launch를 전달하지 않는 한 어떤 프로브도 앱을 실행하지 않습니다. 공통 메커니즘은 scripts/lib/probe-kit.mjs에 있습니다.

릴리스는 패키지별로 태그가 지정되므로 태그가 게시 대상을 나타냅니다: mail-v1.1.0, reminders-v1.1.0, calendar-v1.1.0, core-v1.1.0. 앱은 app-v1.1.0으로 태그가 지정되며 자체 트랙으로 릴리스됩니다 — GitHub 릴리스에 첨부된 서명 및 공증된 Cupertino.zip과 그 SHA-256입니다. docs/distribution.md를 참조하세요.

리포지토리는 mcp-cupertino이고, npm 패키지는 @mgcrea/mcp-apple-*로 유지됩니다. 사람들이 npm에서 그렇게 검색하기 때문입니다. 어느 이름도 중요한 것은 아닙니다. 번들 식별자 io.mgcrea.cupertino 는 실제로 중요한 문자열인데, 변경하면 모든 사용자의 Full Disk Access 권한이 무효화되기 때문입니다.

라이선스

두 가지입니다. 두 부분이 서로 같지 않기 때문입니다.

Cupertino는 Full Disk Access를 요청하므로 소스는 읽을 수 있는 상태로 유지됩니다 — 그러한 권한 부여에 대한 보답이며, 읽는 것이 핵심입니다. 실행은 별개의 문제입니다. 라이선스 확인은 소스에 있으므로 어떤 빌드든 키를 요청하며, 그 키는 여러분의 것이거나 우리의 것입니다. 판매되는 것은 공증된 바이너리와 그 뒤의 유지보수입니다. 서버는 MIT이며 키 없이 자체적으로 실행됩니다. 자세한 이유는 docs/licensing.md에 있습니다.