📧 Gmail 자동화 — 클로드 코드 무료 학습

사전 준비: Google Gmail API 설정

매일 아침 메일 분류에 30분씩 쓰고 계시다면, 이걸 자동화해볼게요. Claude Code가 Gmail에 접근하려면 “열쇠”가 필요해요. Google에서 “이 프로그램이 내 메일에 접근해도 됩니다”라는 허가증을 만드는 거예요.한 번만 설정하면 계속 사용할 수 있어요.

코딩 경험이 없어도 돼요

이 실습에서 여러분이 직접 코드를 작성할 일은 없어요. Claude Code에게 프롬프트 하나를 입력하면, 나머지는 AI가 전부 처리해요. 여러분은 결과를 확인하고 y/n으로 승인만 하면 돼요.

API 키가 필요한가요?

아니요! 많은 분이 “API 키를 발급해야 하나?”라고 걱정하시는데,API 키는 필요 없어요. 필요한 건 OAuth 클라이언트 ID라는 것 하나뿐이에요. 이걸 만들고 브라우저에서 Google 로그인 한 번 하면 끝이에요.

방법이 두 가지 있어요. 상황에 맞는 걸 골라서 따라하세요.

credentials.json 방식

기존 방식. Claude Code가 직접 Gmail API를 호출하는 Python/Node 코드를 작성해요. credentials.json 파일을 작업 폴더에 넣으면 돼요.

범용 · 모든 OS

GWS CLI 방식

2026년에 Google이 공개한 CLI 도구. 터미널에서 바로 gws gmail 명령어로 메일을 조작할 수 있어요.

최신 · Claude Code MCP 연동 가능

공통 단계: OAuth 클라이언트 ID 만들기 (1회)

A, B 어느 방식이든 이 과정은 동일해요. 처음 한 번만 하면 돼요.

Google Cloud Console 접속

브라우저에서 console.cloud.google.com 에 접속하세요. Google 계정으로 로그인하세요.

프로젝트 생성 → Gmail API 활성화

상단에서 “새 프로젝트”를 만들어요 (이름은 아무거나 OK). 그 다음 좌측 메뉴에서 “API 및 서비스” → “라이브러리”로 가서 “Gmail API”를 검색하고 “사용” 버튼을 클릭하세요.

OAuth 동의 화면 설정 + 테스트 사용자 등록

좌측 메뉴에서 “Google Auth Platform” (구 OAuth 동의 화면)으로 이동해요.“Audience” 탭에서 “External”을 선택하고,테스트 사용자에 본인 Gmail을 추가하세요. 이걸 안 하면 나중에 로그인할 때 “access_denied” 에러가 나요.

OAuth 클라이언트 ID 만들기

“Clients” 탭 (또는 “사용자 인증 정보”) → “OAuth 클라이언트 ID 만들기”. 애플리케이션 유형은 “데스크톱 앱”으로 선택하세요.

JSON 다운로드

생성 완료 후 “JSON 다운로드” 버튼을 클릭하세요. 이 파일이 여러분의 “열쇠”예요.

Gmail API 사용 버튼 — Gmail API를 검색하고 “사용” 버튼을 클릭하세요

OAuth 클라이언트 ID 만들기 — 데스크톱 앱 선택 — 애플리케이션 유형에서 “데스크톱 앱”을 선택하세요

Playwright로 이 과정을 자동화할 수 있어요

Step 4에서 설치한 Playwright, 기억하시죠? 사실 위의 Cloud Console 설정 과정도 Playwright로 자동화할 수 있어요. Claude Code에게 이렇게 말해보세요:

“Playwright로 Google Cloud Console에 접속해서 Gmail API 활성화하고 OAuth 클라이언트 ID 만들어줘”

Claude Code가 브라우저를 자동으로 열고, 프로젝트 생성부터 OAuth 설정까지 클릭 하나 없이 전부 처리해줘요. 여러분은 Google 로그인 비밀번호만 입력하면 돼요.

단, Google은 자동화 도구의 로그인을 차단할 수 있어서, 로그인까지는 직접 하고 그 이후 단계만 자동화하는 게 더 안정적이에요.

Acredentials.json 방식

다운로드한 JSON 파일을 credentials.json으로 이름을 바꿔서 작업 폴더에 넣으세요. 끝이에요!

파일 위치 (예시)

~/Desktop/autowork/credentials.json

Claude Code가 이 파일을 읽어서 Gmail API 연결 코드를 자동으로 작성해요. 첫 실행 시 브라우저가 열리고 Google 로그인을 요청해요. 로그인하면 토큰이 저장되고 이후엔 자동으로 연결돼요.

BGWS CLI 방식 (Google Workspace CLI)

2026년에 Google이 공개한 CLI 도구예요. 터미널에서 바로 Gmail, Drive, Sheets, Calendar를 조작할 수 있어요. 심지어 MCP 서버 모드를 지원해서 Claude Code와 직접 연동도 가능해요.

설치

# 1. GitHub Releases에서 gws.exe 다운로드
#    github.com/googleworkspace/google-workspace-cli/releases

# 2. 다운로드한 gws.exe를 npm 글로벌 폴더에 복사
#    보통: %APPDATA%\npm\gws.exe

# 3. 터미널에서 확인
gws --version

Windows npm 설치 에러가 난다면

Windows에서 npm install -g @googleworkspace/cli 실행 시 tar 에러가 발생할 수 있어요. 이 경우 GitHub Releases 페이지에서 gws.exe를 직접 다운로드해서 npm 글로벌 bin 폴더에 넣으세요. 기존 npm이 만든 gws.cmd, gws.ps1 파일이 있다면 삭제하세요.

인증 (로그인)

위에서 다운로드한 JSON 파일을 client_secret.json으로 이름을 바꿔서 GWS 설정 폴더에 넣으세요.

# JSON 파일을 GWS 설정 폴더에 복사
# %APPDATA%\gws\client_secret.json

# 로그인
gws auth login

브라우저가 열리고 Google 로그인 화면이 나와요. 로그인하면 끝!

테스트

터미널

# Gmail 메일 목록 가져오기
gws gmail users messages list --params '{"userId": "me"}'

메일 ID 목록이 출력되면 성공이에요. 이제 Claude Code에서 GWS CLI를 활용할 수 있어요.

자주 겪는 문제 & 해결법

access_denied 에러가 나요

“개발자가 액세스 권한을 부여하지 않았습니다” 에러가 나면,테스트 사용자 등록을 빠뜨린 거예요. Google Cloud Console → Google Auth Platform → Audience 탭에서 본인 Gmail을 테스트 사용자로 추가하세요.

“부적격 계정” 경고가 뜨더라도 실제로는 추가돼요. 목록에 나타나면 OK.

테스트 모드 토큰 유효기간

Google OAuth “테스트 모드”의 토큰은 7일 후 만료돼요. 7일이 지나면 다시 로그인해야 해요. 프로덕션으로 전환하면 이 제한이 없어지지만, 개인 사용이라면 7일마다 재인증하는 것도 크게 불편하지 않아요.

이 과정이 복잡하게 느껴지시나요?

Google Cloud Console이 처음이면 당연히 복잡하게 느껴져요. 근데 걱정 마세요. Claude Code에게 도움을 요청할 수 있거든요!

터미널에서 Claude Code를 실행하고 이렇게 물어보세요:

“Gmail API용 OAuth 설정하는 방법을 단계별로 알려줘”

화면을 보면서 하나씩 따라하면 돼요. 모르는 부분은 계속 물어보세요.

바로 실행하기

credentials.json이 작업 폴더에 준비됐으면, 이제 Claude Code에게 시킬 차례예요. 터미널에서 Claude Code를 실행하고(claude 입력), 아래 프롬프트를 그대로 입력하세요.

Claude Code에 입력할 프롬프트

credentials.json으로
Gmail 자동화 해줘.
메일 분류하고, 뉴스레터는
읽음처리, 업무중요는 답장
초안 잡아줘. emails.json 저장.

이게 전부예요.

프롬프트 하나로 Claude가 아래 전체를 알아서 처리해요.

Claude가 자동으로 하는 것

🔗

Gmail API 연결 코드 작성

credentials.json을 읽어서 OAuth 인증 코드를 자동 생성

📨

메일 50개 수집 + 4카테고리 분류

받은편지함에서 메일을 가져와서 업무중요/뉴스레터/알림/기타로 분류

👁️

뉴스레터 & 알림 자동 읽음 처리

중요하지 않은 메일은 읽음 표시로 자동 변경

✏️

업무 중요 메일마다 답장 초안 작성

메일 내용을 분석해서 적절한 답변을 AI가 작성

✅

y/n 승인 후 Gmail Draft 저장

초안을 보여주고, 승인하면 Gmail 임시보관함에 저장

💾

전체 결과 emails.json 저장

분류 결과와 처리 내역을 JSON 파일로 기록

Claude Code 구독이 필요해요

Claude Code를 사용하려면 Claude 구독이 필요해요. API 키 같은 복잡한 설정은 필요 없고, claude.ai에서 구독만 하면 돼요.

추천 플랜: Claude Max ($100/월) — Claude Code 사용량이 넉넉해서 자동화 프로젝트를 여유 있게 진행할 수 있어요. Pro 플랜($20/월)으로도 시작할 수 있지만, 실습을 많이 하다 보면 사용량 제한에 걸릴 수 있어요.

MCP를 사용한 Gmail 접근도 가능해요

OAuth 설정이 번거로우면, Gmail MCP 서버를 사용하는 방법도 있어요. MCP(Model Context Protocol)는 Claude Code가 외부 서비스에 접근하는 표준 방식이에요. 커뮤니티에서 만든 Gmail MCP 서버를 연결하면, OAuth 설정 없이도 Gmail에 접근할 수 있어요.

MCP에 대해 더 알고 싶다면, Claude Code 안에서 “MCP 서버 설정 방법 알려줘”라고 물어보세요.

실행 결과 확인

프롬프트를 입력하면 Claude Code가 코드를 작성하고 실행해요. 터미널에 아래와 같은 결과가 나타나요.

1단계: 메일 수집 + 분류 + 자동 읽음 처리

터미널 실행 결과 (예시)

📧 Gmail 자동화 시작...

✅ Gmail API 연결 성공
📨 메일 50개 수집 완료

📊 분류 결과:
  업무 중요  : 8건
  뉴스레터   : 22건
  알림       : 15건
  기타       : 5건

👁️ 뉴스레터 22건 읽음 처리 완료
👁️ 알림 15건 읽음 처리 완료

2단계: 답장 초안 승인 화면

터미널 실행 결과 (예시)

✏️ 업무 중요 메일 답장 초안 작성 중...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📩 From: 김팀장 <teamlead@company.com>
📋 제목: 3월 프로젝트 일정 확인 부탁

📝 답장 초안:
"김팀장님, 안녕하세요.
3월 프로젝트 일정 확인했습니다.
현재 진행 상황과 함께 금주 금요일까지
업데이트된 일정표 공유드리겠습니다.
감사합니다."

💾 이 초안을 Gmail Draft에 저장할까요? (y/n): y
✅ Draft 저장 완료!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📩 From: 마케팅팀 <marketing@company.com>
📋 제목: 다음 주 미팅 자료 요청

📝 답장 초안:
"안녕하세요, 마케팅팀.
요청하신 미팅 자료 준비하겠습니다.
월요일 오전까지 공유드릴 수 있을까요?
필요한 항목이 더 있으시면 알려주세요."

💾 이 초안을 Gmail Draft에 저장할까요? (y/n): y
✅ Draft 저장 완료!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 최종 결과:
  처리된 메일: 50건
  읽음 처리: 37건
  답장 초안: 8건 (승인 8건)
  저장: emails.json ✅

사람이 한 것

프롬프트 1개 + y/n 클릭 몇 번

AI가 한 것

나머지 전부

이해하기: 자동화 파이프라인 6단계

방금 실행한 자동화가 내부적으로 어떻게 동작하는지 알아볼게요. 아래 6단계로 돌아가는 구조예요. 복잡해 보이지만 걱정 마세요 — 여러분은 이미 프롬프트 하나로 이 전체를 실행한 거예요.

수집

Gmail API로 받은편지함에서 최근 메일 50개를 가져와요. 보낸 사람, 제목, 본문 내용을 모두 읽어와요.

Gmail API

분류

AI가 각 메일을 분석해서 4개 카테고리로 자동 분류해요.

업무 중요뉴스레터알림기타

읽음 처리

뉴스레터와 알림으로 분류된 메일은 자동으로 읽음 표시해요. 더 이상 수동으로 하나씩 클릭할 필요가 없어요.

자동 처리 (사람 개입 없음)

답장 초안

업무 중요로 분류된 메일마다 AI가 답장 초안을 작성해요. 메일 내용을 분석해서 적절한 답변을 자동으로 만들어줘요.

AI 초안 생성

승인

AI가 만든 초안은 바로 보내지 않아요. 터미널에 초안 내용이 표시되고, 여러분이 y를 눌러야 Gmail 임시보관함(Draft)에 저장돼요.

사람이 확인 (안전장치)

반복 실행

완성된 스크립트를 매일 아침 자동 실행되도록 스케줄에 등록해요. 한 번 설정하면 매일 출근 전에 메일 정리가 끝나 있어요.

cron / Task Scheduler

핵심 포인트

이 6단계를 여러분이 직접 코딩하는 게 아니에요. Claude Code에게 프롬프트 하나만 주면, 이 전체 파이프라인을 자동으로 만들어줘요.

좋은 프롬프트 작성법 3가지 공식

Claude Code에게 일을 시킬 때, 프롬프트를 어떻게 쓰느냐에 따라 결과가 달라져요. 아래 3가지 공식만 기억하면 돼요.

공식 1: 파일 이름을 명시하라

Bad	Good
❌ “이 파일 분석해줘”	✅ “sales.csv를 읽어서”
❌ “데이터 정리해줘”	✅ “report.xlsx 열어서”

어떤 파일인지 정확히 알려줘야 AI가 바로 실행할 수 있어요.

공식 2: 결과물을 명시하라

Bad	Good
❌ “정리해줘”	✅ “요약.xlsx로 저장해줘”
❌ “분석해줘”	✅ “차트 포함한 보고서.html 만들어줘”

결과물의 형식과 파일명까지 알려주면, 원하는 형태로 정확히 저장돼요.

공식 3: 이어서 수정하라

한 번에 완벽할 필요가 없어요. 결과를 보고 추가 요청하면 돼요.

1차: “sales.csv 읽어서 부서별 집계표 만들어줘”

2차: “다시 해줘, 이번엔 차트도 추가해”

3차: “차트 색상을 파란색 계열로 바꿔줘”

프롬프트 공식

[파일/상황] + [원하는 처리] + [결과물 형식/파일명]

예: “sales.csv를 읽어서 부서별 매출 집계하고 요약.xlsx로 저장해줘”

직접 해보기

이제 직접 실행해볼게요. 아래 단계를 따라하세요.

실행 순서

작업 폴더로 이동

credentials.json이 있는 폴더로 이동하세요.

Claude Code 실행

claude

프롬프트 입력

credentials.json으로
Gmail 자동화 해줘.
메일 분류하고, 뉴스레터는
읽음처리, 업무중요는 답장
초안 잡아줘. emails.json 저장.

실행 과정 지켜보기

Claude가 코드를 작성하고 실행하는 과정을 지켜보세요.

답장 초안 승인

초안이 표시되면 y 또는 n으로 응답하세요.

실행 중 주의사항

Google 로그인 창이 떠요 — 처음 실행 시 브라우저에서 Google 로그인 화면이 열려요. “허용”을 클릭하세요. “확인되지 않은 앱” 경고가 나오면 “고급” → “계속”을 누르세요.
y/n 선택은 원하는 대로 — 답장 초안이 마음에 들면 y, 아니면 n을 누르세요. n을 눌러도 아무 문제 없어요. Draft에 저장하지 않을 뿐이에요.
에러가 나도 당황하지 마세요 — Claude Code는 에러가 발생하면 스스로 원인을 분석하고 수정해요. 가만히 지켜보면 자동으로 해결하는 경우가 대부분이에요.

확인 체크리스트

emails.json 파일이 작업 폴더에 생성되었다터미널에 메일 분류 결과 (업무중요/뉴스레터/알림/기타)가 출력되었다Gmail 임시보관함에 Draft가 1개 이상 저장되었다

잘 안 되나요?

가장 흔한 문제는 credentials.json 파일 위치예요. 작업 폴더에 파일이 있는지 다시 확인해보세요.

그래도 안 되면 Claude Code에게 이렇게 물어보세요: “에러 원인을 찾아서 해결해줘”

매일 아침 자동 실행 설정

자동화 스크립트가 완성됐으면, 매일 아침 자동으로 실행되게 만들 수 있어요. Claude Code가 만든 Python 스크립트를 스케줄러에 등록하면 돼요.

Claude Code에게 이렇게 요청하세요:

Claude Code에 입력

이 스크립트를 매일 아침 9시에
자동 실행되도록 등록해줘

Claude Code가 운영체제에 맞게 자동으로 설정해줘요. 직접 설정하고 싶다면 아래를 참고하세요.

OS별 스케줄 설정 방법

# Windows Task Scheduler 사용
# 1. 시작 메뉴 → "작업 스케줄러" 검색 → 실행
# 2. "기본 작업 만들기" 클릭
# 3. 이름: "Gmail 자동화"
# 4. 트리거: "매일" → 오전 9:00
# 5. 동작: "프로그램 시작"
#    프로그램: python
#    인수: gmail_auto.py
#    시작 위치: C:\Users\PC\Desktop\autowork
# 6. 마침

# 또는 PowerShell로 한 번에 등록:
$action = New-ScheduledTaskAction `
  -Execute "python" `
  -Argument "gmail_auto.py" `
  -WorkingDirectory "$HOME\Desktop\autowork"
$trigger = New-ScheduledTaskTrigger `
  -Daily -At 9am
Register-ScheduledTask `
  -TaskName "Gmail자동화" `
  -Action $action `
  -Trigger $trigger

스케줄 등록도 Claude Code에게 맡기세요

위 설정이 복잡하게 느껴진다면, 그냥 Claude Code에게 “매일 아침 9시에 자동 실행되게 해줘”라고 말하면 돼요. OS를 자동으로 감지해서 알아서 등록해줘요.

정리

오늘 만든 Gmail 자동화 흐름

API 인증→메일 수집→AI 분류→읽음 처리→답장 초안→승인→스케줄

사람이 한 것: 프롬프트 1개 + y/n 몇 번

AI가 한 것: 나머지 전부

코드를 직접 짜지 않아도, 매일 30분 걸리던 메일 정리가 자동화돼요.

Gmail 말고 다른 것도?

같은 방식으로 엑셀 집계, PPT 생성 같은 것도 자동화할 수 있어요. 매주 반복하는 엑셀 작업이 있다면, 그것도 프롬프트 하나로 해결 가능하거든요.