MailSyncMCP

Claude에서 Apple Mail의 모든 계정을 검색하고 읽고 답장하세요. 비밀번호 하나도 넘기지 않고.

Gmail, Microsoft 365, iCloud 및 사용자 지정 도메인 IMAP 모두에서 작동합니다. 각 제공업체와 직접 통신하는 대신 Mail이 이미 동기화한 내용을 읽기 때문입니다. Mac에서 완전히 실행됩니다. 어디에도 업로드되지 않습니다.

이렇게 작동하는 이유

Apple Mail은 이미 모든 계정을 동기화하고 Keychain에 자격 증명을 보관하며 자체적으로 갱신합니다. 이 서버는 Mail의 로컬 저장소를 읽고 Mail에 작성을 요청합니다. 비밀번호나 토큰을 절대 보지 않으며, 저장하지도 않고, 재인증을 유발하지도 않습니다. 계정을 추가한다는 것은 Mail에서 추가한다는 뜻입니다. 여기서 변경되는 것은 없습니다.

대안인 각 제공업체와 직접 통신하는 방식은 Google Cloud 프로젝트, Azure 앱 등록, 계정별 리프레시 토큰이 필요합니다. 더 나쁜 것은, 업무용 및 대학 계정은 일반적으로 잠겨 있어서 타사 OAuth 앱에 관리자 동의가 필요한데, 이는 종종 거부됩니다. Mail이 이미 동기화한 내용을 읽는 방식은 이 모든 것을 우회합니다.

Related MCP server: macos-mail-mcp

안전

읽기와 검색은 자유롭습니다. 보내기는 그렇지 않습니다.

1. 자격 증명 없음. 유출되거나 만료될 것이 없습니다.

2. 2단계 커밋. prepare_* 도구는 요청을 검증하고 전체 미리보기를 렌더링하며 5분 후 만료되는 일회용 토큰을 반환합니다. 아무것도 변경하지 않습니다. commit_action(token)은 유일하게 실제로 작동하는 도구이며, 토큰만 받고 다른 것은 받지 않으므로 나가는 메시지는 항상 표시된 메시지입니다.

3. 클라이언트 권한 프롬프트 commit_action 시.

4. 신뢰할 수 없는 콘텐츠 차단. 메시지 본문은 데이터로 감싸져 표시됩니다. 토큰은 렌더링된 미리보기만 만들 수 있으므로 이메일에 포함된 지시문이 메일을 보내게 할 수 없습니다.

5. 감사 로그 ~/.local/share/mailsync/audit.jsonl에 추가 전용으로 기록됩니다.

서버는 stdio만 사용합니다. 리스너, 데몬, 타이머가 없으므로 채팅 세션에서 도구가 호출될 때만 작동합니다.

MAILSYNC_READ_ONLY=1을 설정하면 세션 전체에서 작성을 비활성화할 수 있습니다.

AppleScript에 관하여

applescript/의 모든 스크립트는 argv를 통해 값을 받는 정적 파일입니다. 스크립트 텍스트가 생성되지 않으므로 이메일의 따옴표, 백슬래시, 줄바꿈 및 AppleScript 구문은 리터럴 데이터로 유지됩니다. tests/test_applescript_safety.py는 적대적 페이로드에 대해 이를 검증합니다. 다른 Apple Mail MCP 서버는 메시지 데이터를 스크립트 소스에 연결하고 이스케이프 함수로 방어합니다. 이 서버는 이스케이프할 주입 표면이 없습니다.

도구

읽기: list_accounts, search_mail, get_message, get_thread, list_attachments, save_attachment, mailbox_stats, open_in_mail, refresh_index

작성: prepare_send, prepare_reply, prepare_forward, list_pending, commit_action

메일을 플래그 지정, 이동, 보관 또는 삭제하는 기능은 의도적으로 없습니다. 이 서버가 변경할 수 있는 유일한 것은 새 메시지가 전송되거나 초안이 작성되는 것입니다.

Mail로의 링크

반환되는 모든 메시지에는 RFC-822 Message-ID에서 생성된 message:// URL이 포함됩니다. 클릭하면 Apple Mail에서 해당 메시지가 열리므로 채팅의 답변을 실제 메시지로 추적할 수 있습니다. Mail이 로컬에 저장하지 않은 메시지에는 Message-ID가 없으므로 링크도 없습니다.

채팅 클라이언트는 링크 대상을 허용된 스킴 목록(http, https, mailto)으로 제한하므로 message:// 링크는 클릭할 수 없는 텍스트로 렌더링됩니다. open_in_mail 도구는 바로 그 이유로 존재합니다: 메시지 열기를 요청하면 Mail로 바로 이동합니다. URL은 여전히 출력되므로 복사하거나 채팅 외부에서 사용할 수 있습니다.

open_in_mail은 whole_thread=True를 받지만 Mail은 각 메시지를 자체 창에서 엽니다: 스크립트 가능한 스레드 보기가 없습니다. 기본 뷰어에서 set selected messages는 macOS 26 대화 모드에서 반복적으로 테스트했지만 작동하지 않으며 AppleScript 브리지가 강제 변환할 수 없는 객체를 반환합니다. get_thread가 대화를 읽는 더 나은 방법입니다.

링크는 항상 단일 메시지를 열며 그 주변의 대화는 열지 않습니다. Mail은 세 가지 URL 스킴(mailto, message, mail-pref-pane)만 등록하며 그 중 어느 것도 스레드를 대상으로 하지 않습니다. AppleScript를 통해 Mail의 자체 스레드 목록을 구동하는 것은 시도했지만 포기했습니다: macOS 26에서 set selected messages는 Gmail All Mail 사서함과 일반 INBOX 모두에서 잘못된 대화를 선택하거나 빈 선택을 보고합니다. 그런 것을 제공하는 대신 get_message는 메시지별 링크와 함께 나머지 대화를 나열하고 get_thread는 전체 교환을 순서대로 렌더링합니다.

설치

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m mailsync --build-index

등록

Claude Code와 Claude for Desktop은 별도의 앱이며 별도의 구성 파일이 있습니다. 하나에 등록해도 다른 하나에는 아무 효과가 없습니다:

사용하는 쪽에 동일한 항목을 추가하고 venv의 Python을 가리키게 하세요:

{
  "mcpServers": {
    "mailsync": {
      "command": "/absolute/path/to/Apple-Mail-Sync-MCP/.venv/bin/python",
      "args": ["-m", "mailsync"]
    }
  }
}

패키지가 pip install -e .로 venv에 설치되므로 항목은 작업 디렉터리에 의존하지 않습니다. 이후 앱을 종료하고 다시 여세요.

이와 같은 로컬 서버는 Mac에서 자식 프로세스로 실행되므로 Mac에서 실행 중인 앱에서만 사용할 수 있습니다. 브라우저의 claude.ai는 접근할 수 없습니다.

각 표면은 자체 OS 프로세스를 시작합니다. stdio는 하나를 공유할 방법이 없습니다. 두 항목이 동일한 설치 패키지를 실행하고 모든 프로세스가 ~/.local/share/mailsync/mailsync.db의 동일한 인덱스를 읽고 쓰기 때문에 설정이 분기되지 않습니다. 코드를 한 번 편집하면 두 표면 모두 다음 재시작 시 반영합니다. 동시 접근은 안전합니다: 인덱스는 WAL 모드와 busy timeout으로 실행되며 5개의 읽기와 2개의 동시 재구축으로 테스트되었습니다.

전체 디스크 접근

~/Library/Mail은 전체 디스크 접근으로 보호되며 MCP 서버는 이를 시작한 앱의 권한을 상속합니다. Claude Code와 Claude for Desktop은 별도의 TCC 클라이언트이므로 하나는 작동하고 다른 하나는 작동하지 않을 수 있습니다. 시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근에서 권한을 부여한 후 앱을 완전히 종료하고 다시 여세요.

이 권한이 없어도 검색과 읽기는 보호 영역 밖에 있는 로컬 인덱스에서 계속 작동합니다. refresh_index만 실패하므로 데이터가 오래될 수 있습니다. 도구는 불명확하게 실패하는 대신 그 사실을 명확히 알려줍니다.

작성에는 추가로 Mail.app 실행과 자동화 권한이 필요하며, macOS는 첫 사용 시 이를 묻습니다.

부분 메시지

Mail은 완전히 다운로드하지 않은 메시지의 헤더 전용 사본을 보관합니다. 일반적인 사서함에서는 약 4분의 1이 그렇습니다. 이러한 메시지는 발신자, 제목, 날짜 및 Mail이 저장한 미리보기 텍스트로 검색할 수 있습니다. get_message는 fetch_if_partial=True를 받아 Mail에 전체 소스를 요청하며, 그러면 서버에서 본문을 가져옵니다. Mail이 실행 중이어야 하므로 자동이 아닌 선택 사항입니다.

인덱스 작동 방식

~/.local/share/mailsync/mailsync.db는 ~/Library/Mail/V10/**/*.emlx에서 추출한 메시지 본문에 대한 FTS5 인덱스를 보유하며 Mail 자체 Envelope Index에 키가 지정됩니다. Mail의 데이터베이스는 읽기 전에 복사되며 쓰기 가능하게 열리거나 잠기지 않습니다.

첫 구축은 12,800개 메시지에 약 1분이 걸립니다. 이후 새로고침은 1~2초입니다. mtime이 변경된 파일만 다시 파싱되기 때문입니다. 검색은 수 밀리초에서 수십 밀리초 내에 반환됩니다.

본문은 Mail이 전체를 다운로드한 약 70%의 메시지에서 검색할 수 있습니다. 나머지는 발신자, 제목, 날짜 및 Mail 자체 미리보기 텍스트로 검색할 수 있으며 get_message는 해당 정보로 대체됩니다. Mail이 동기화함에 따라 적용 범위는 저절로 늘어납니다.

유지 관리

Apple의 Envelope Index 스키마는 문서화되지 않았으며 macOS 업데이트에서 변경될 수 있습니다. 모든 것은 mailsync/index.py에 국한되어 있으며 본문 인덱스는 --build-index --full로 언제든지 .emlx 파일에서 다시 구축할 수 있습니다.