Gmail 첨부파일 다운로드

배경

claude.ai Gmail MCP는 검색·본문 조회만 지원하고 첨부파일 다운로드 도구가 없다.
이 스킬은 Gmail IMAP(X-GM-RAW)으로 Gmail 검색 문법을 그대로 써서 첨부를 로컬에 저장한다.

사전 조건 (1회 설정)

1. Google 계정에 2단계 인증 활성화 후 앱 비밀번호 발급: https://myaccount.google.com/apppasswords
2. ~/.gmail_app.env 파일 생성 (커밋 금지):

   GMAIL_USER=your@gmail.com
   GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx

3. Gmail 설정 → 전달 및 POP/IMAP → IMAP 사용 확인 (기본 활성).

인증 파일이 없으면 스크립트가 설정 안내를 출력하고 종료한다. 이때는 사용자에게 위 설정을 요청할 것.

사용법

# 목록만 확인 (다운로드 전 확인 권장)
python "%USERPROFILE%/.claude/skills/gmail-attachments/scripts/download_attachments.py" \
    --query "subject:quant has:attachment" --list

# 다운로드
python "%USERPROFILE%/.claude/skills/gmail-attachments/scripts/download_attachments.py" \
    --query "subject:quant has:attachment newer_than:90d" --out "C:/dest/folder"

• --query: Gmail 검색 문법 그대로 (from:, subject:, has:attachment, newer_than:30d, filename:pdf 등). 한글 검색어 지원(UTF-8 리터럴).
• --limit N: 최신 N개 메일만 처리 (기본 20).
• --mailbox: 기본 전체보관함([Gmail]/All Mail), 실패 시 INBOX 자동 폴백.
• 파일명 충돌 시 _1, _2 자동 접미. 한글/MIME 인코딩 파일명 자동 복원.

워크플로우 권장

1. Gmail MCP search_threads로 대상 메일·첨부 파일명 먼저 확인.
2. --list로 IMAP 검색 결과가 MCP 결과와 일치하는지 확인.
3. --out으로 실제 다운로드 → 저장 파일을 Read로 검증(페이지 수·내용 확인).

주의

• 앱 비밀번호는 ~/.gmail_app.env에만 두고 어떤 저장소에도 커밋하지 말 것.
• 상용 서적 등 저작권 자료는 개인 보관 용도로만 사용.