Apple Mail MCP Server

[

Apple Mail에 프로그래밍 방식으로 접근할 수 있게 해 주는 MCP 서버로, Claude와 같은 AI 어시스턴트가 macOS에서 이메일을 읽고, 보내고, 검색하고, 관리할 수 있습니다.

⚠️ Pre-1.0 — 호환되지 않는 변경이 예상됩니다. 프로젝트가 성숙해짐에 따라 MCP 도구의 표면(도구 이름, 매개변수, 반환 형식)은 여전히 진화하고 있습니다. 특정 버전(예: apple-mail-mcp==0.8.1)에 고정하고 업그레이드 전 CHANGELOG를 검토하세요.

도구 (23)

핵심: list_mailboxes, search_messages, get_messages, update_message 초안 수명 주기: create_draft, update_draft, delete_draft 메일함 CRUD: create_mailbox, update_mailbox, delete_mailbox 첨부 파일 및 관리: save_attachments, delete_messages 탐색 및 규칙: list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule 템플릿: list_templates, get_template, save_template, delete_template, render_template

전체 매개변수 및 반환 형식 문서는 docs/reference/TOOLS.md를 참조하세요.

Related MCP server: apple-mail-mcp

사전 요구 사항

• macOS 10.15(Catalina) 이상

• Python 3.10 이상

• Apple Mail에 계정이 하나 이상 설정되어 있어야 함

• uv(권장) 또는 pip

설치

# From source (recommended for development)
git clone https://github.com/s-morgan-jeffries/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

구성

Claude Desktop 구성 파일(~/Library/Application Support/Claude/claude_desktop_config.json)에 추가하세요.

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

권한

첫 실행 시 macOS가 자동화 접근 권한을 요청합니다. 시스템 설정 > 개인정보 보호 및 보안 > 자동화 > 터미널(또는 IDE) 에서 권한을 부여하세요.

선택 사항: IMAP을 통한 더 빠른 검색

search_messages는 기본적으로 AppleScript를 통해 작동합니다. 메시지가 수천 개에 달하는 대용량 메일함에서는 AppleScript의 whose 절이 쿼리당 1–5초 걸릴 수 있습니다. 더 빠른 서버 측 검색을 원한다면 계정별(account)로 키체인 항목을 추가해 IMAP 검색을 활성화할 수 있습니다.

작동 방식. 계정에 키체인 항목이 있으면 서버는 IMAP(빠른 서버 측 SEARCH)을 사용합니다. 그렇지 않으면, 또는 IMAP 실패(오프라인, 잘못된 비밀번호, 시간 초과)가 발생하면 자동으로 AppleScript로 대체됩니다. 기능이 손실되는 일은 없습니다. IMAP이 구성되어 있고 연결 가능할 때만 속도가 빨라집니다. 구성 플래그나 환경 변수도 필요 없고, 키체인 항목의 존재 자체가 옵트인(opt-in)입니다.

계정별 일회성 설정.

1. 제공 업체에서 앱별 비밀번호를 생성합니다. 절차는 업체마다 다릅니다.

   • iCloud: appleid.apple.com/account/manage → 앱별 비밀번호. Apple ID에 2FA(이중 인증)가 필요합니다(기본값).

   • Gmail: myaccount.google.com/apppasswords → 앱 비밀번호. Google 계정에서 2단계 인증이 설정되어 있어야 합니다.

   • Yahoo / Fastmail / AOL: 제공자의 계정 보안 설정에서 앱 비밀번호를 생성하세요.

2. setup-imap 하위 명령을 실행합니다. 비밀번호를 묻는 메시지가 표시되며(입력 내용이 보이지 않음), 키체인 항목을 생성하고, 연결을 통해 확인합니다.

   apple-mail-mcp setup-imap --account iCloud

   Mail.app에 표시된 계정 이름(예: iCloud, Gmail, "Yahoo!")을 그대로 입력하세요. 명령줄은:

   • Mail.app에서 계정의 기본 이메일을 조회하며(--email로 재정의 가능),

   • getpass를 통해 비밀번호를 입력받으므로 비밀번호가 셸 히스토리에 남지 않으며,

   • 키체인의 apple-mail-mcp.imap.<account>에 항목을 작성하며(동일 항목이 이미 있으면 새 비밀번호로 업데이트),

   • IMAP 연결을 열고 실제 LOGIN을 수행해 비밀번호가 작동하는지 확인합니다. 거부되면 키체인 항목을 롤백하므로 깨진 항목을 남기지 않고 다시 시도할 수 있습니다.

3. 다음 IMAP 기반 호출에서 "security uses를 원할 때 로그인 키체인" 권한 요청이 한 번 표시되면 **항상 허용(Always Allow)**을 클릭하세요.

나중에 항목을 제거하려면: apple-mail-mcp setup-imap --account iCloud --uninstall 을 실행하세요.

설정 확인. setup-imap 명령이 이 작업을 이미 수행해 줍니다. 나중에 다시 확인하려면:

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

IMAP이 정상 작동하면 호출 결과가 약 1초 만에 반환됩니다. WARNING 로그를 통해 대체된다는 메시지가 뜨면(--log-level=DEBUG로 확인), 계정 이름이 Mail.app의 계정 이름과 정확히 일치하는지, 키체인 항목의 이메일이 email addresses of account가 반환하는 값과 일치하는지 확인하세요.

알려진 공급자 특이사항.

• iCloud: IMAP 서버는 로그인 사용자 이름으로 Apple ID 이메일이 아닌 @icloud.com / @me.com 별칭을 허용합니다. 이 때문에 서버(및 setup-imap)는 Mail.app에서 email addresses of account를 읽습니다.

• Yahoo: 앱 비밀번호 이용이 거의 완전히 중단되었으며, 모든 계정에서 옵션이 제공되지 않을 수 있습니다. Yahoo 계정 보안 페이지에 옵션이 표시되지 않으면 해당 계정은 IMAP 설정이 불가능하고 AppleScript가 유일한 방법입니다.

• Google: 2단계 인증이 설정되어 있어야 합니다. Google Workspace 관리자가 테넌트 단위에서 앱 비밀번호를 차단한 경우 해당 계정에는 IMAP 설정이 불가능합니다.

• Gmail 스레드 검색 — All Mail 보이는 절충. 스레드 인식 쿼리에서 내부적으로 사용되는 find_thread_members는 [Gmail]/All Mail이 IMAP에 표시될 때 가장 빠릅니다. 이 경로는 라운드 트립이 약 5회이며 메일함 수와 무관합니다. 많은 사용자가 모든 메시지를 중복시킨다는 이유로 All Mail을 숨겨 둡니다(Gmail 설정 → 전달 및 POP/IMAP → 폴더 크기 제한 → "IMAP에서 표시 안 함"). All Mail이 숨겨져 있으면 사서함별 X-GM-THRID 반복으로 대체되며(여전히 일반 BFS보다 약 6배 빠르지만 라벨 개수에 비례 — 라벨 92개 계정에서 약 25초), 속도를 원하면 All Mail을 표시하고, 깔끔한 IMAP 폴더 목록을 원하면 숨겨두세요.

쓰기 작업(create_draft, update_draft, 그리고 send_now=true 전송 경로 포함)은 IMAP 설정과 무관하게 항상 AppleScript를 사용합니다. 이러한 작업은 Mail.app의 작성 UI가 필요하기 때문입니다.

개발

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

분기 규칙

{type}/issue-{num}-{description} — 예: feature/issue-42-thread-support

아키텍처

server.py (FastMCP tools — thin orchestration)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py — MCP 도구 등록, 입력 검증, 응답 포맷

• server.py

• mail_connector.py — 모든 AppleScript 생성 및 실행

• security.py — 입력 살쟁, 감사 로그, 확인 흐름

• utils.py — 순수 함수: 이스케이프, 파싱, 검증

• exceptions.py — 유형별 예외 계층 구조

보안

• 로컬에서만 실행(클라우드 처리 없음)

• 기존 Mail.app 인증 사용(자격 증명 저장 안 함)

• 모든 입력은 살장 및 이스케이프 처리됨

• 파괴적인 작업은 확인 절차를 거침

• 작업 감사 로그를 기록함

• 정책은 SECURITY.md에서, 상세 분석은 docs/SECURITY.md를 참조하세요.

기여

개발 워크플로, 코딩 표준, PR 절차는 CONTRIBUTING.md를 참조하세요.

라이선스

MIT