gmail-mcp-server

send_email이라는 단일 도구를 제공하는 MCP 서버로, Gmail API를 통해 Gmail 메시지(선택적으로 파일 첨부 포함)를 전송합니다. Claude Code 내부에서 로컬 stdio MCP 서버로 사용되도록 제작되었습니다.

범위는 의도적으로 좁게 잡았습니다. gmail.send만 허용하며(사서함에 대한 읽기/수정 권한 없음) — 메일 전송만 하는 도구에 최소 권한을 적용한 것입니다.

이 README는 실제 첫 설정 과정을 바탕으로 작성되었으며, 진행하면서 발생한 모든 오류를 포함합니다. 위에서 아래로 순서대로 따라 하면 그런 오류를 만나지 않을 것입니다.

PowerShell 참고: &&는 Windows PowerShell에서 명령 구분자로 작동하지 않습니다(bash/cmd 문법입니다). 아래의 모든 복합 명령줄은 별도의 줄로 작성했으며, 한 줄로 실행하려면 ;를 사용하세요: cd C:\Users\GaneshGupta\gmail-mcp-server; python auth_setup.py

1. Google Cloud — API 활성화 및 OAuth 사용자 인증 정보 생성

Google 콘솔의 이 UI는 최근 "OAuth consent screen"에서 Google Auth Platform으로 이름이 바뀌었으며, 설정이 왼쪽 내비게이션의 별도 페이지(Branding / Audience / Clients / Data Access / Verification Center)로 분리되어 있습니다. 아래 단계는 현재 이름을 기준으로 합니다.

1. console.cloud.google.com로 이동합니다. 새 프로젝트를 만들거나 기존 프로젝트를 재사용하세요.

2. APIs & Services → Library → "Gmail API" 검색 → Enable.

3. APIs & Services → OAuth consent screen(여기서 새 Google Auth Platform 섹션으로 이동합니다) → Branding 페이지를 작성합니다:

   • App name: 아무 이름이나 가능, 예: gmail-mcp-tool

   • User support email: 본인의 Gmail 주소

   • Developer contact email: 본인의 Gmail 주소

   • 로고/App domain 필드는 지금은 비워 두세요 — "incomplete configuration" 오류가 발생하면 4단계에서 App domain으로 돌아오게 됩니다. 임의로 미리 채우지 말고, 실제로 해당 오류가 나타날 때만 작성하세요.

4. Audience 페이지(왼쪽 내비게이션) → Test users 아래 → + Add users → 본인의 Gmail 주소(메일을 보내는 계정) 입력 → Save.

   "Add users"가 차단된 경우 — *"Your app's OAuth configuration is incomplete... Please visit the Branding page"*라는 노란 배너가 표시됩니다. 이는 gmail.send가 민감한 범위(sensitive scope)이기 때문이며, Testing 전용 앱에서도 App domain 필드가 비어 있으면 안 됩니다. 해결 방법:

   • Branding → App domain으로 이동하여 입력합니다:

     • Application home page: https://example.com

     • Application privacy policy link: https://example.com/privacy

     • Application terms of service link: https://example.com/terms

   • 그러면 Authorized domains 필드가 나타납니다. https:// 접두사 없이 순수 도메인만 입력하세요:

     • 올바른 예: example.com

     • 잘못된 예("Invalid domain: must not specify the scheme" 오류로 거부됨): https://example.com

   • Branding에서 Save를 클릭합니다.("Branding changes saved!" 토스트가 표시됩니다.)

   • Audience → Add users로 돌아가 다시 시도하면 이번에는 정상 진행됩니다.

   이 URL은 실제로 존재하거나 동작할 필요는 없습니다. 앱이 Testing 상태인 동안 Google은 이 URL을 검증하지 않으며, 필드가 채워져 있기만 하면 됩니다.

5. Clients 페이지(왼쪽 내비게이션) → + Create client:

   • Application type: Desktop app

   • Name: 아무 이름이나 가능, 예: gmail-mcp-desktop

   • Create → Download JSON(생성 직후 버튼이 나타남)

6. 다운로드된 파일 이름은 client_secret_<long-id>.apps.googleusercontent.com.json과 같은 형식입니다. 이름을 정확히 client_secret.json으로 바꾸고 다음 위치로 이동하세요:

   C:\Users\GaneshGupta\gmail-mcp-server\credentials\client_secret.json

   파일 이름이 정확해야 합니다. gmail_auth.py는 해당 이름으로 파일을 찾으며, 이름이 일치하지 않으면 FileNotFoundError를 발생시킵니다(이 과정에서 가장 흔히 틀리는 부분입니다).

Related MCP server: Gmail MCP Server

2. 의존성 설치

cd C:\Users\GaneshGupta\gmail-mcp-server
pip install -r requirements.txt

3. 1회성 로그인

python auth_setup.py

진행 과정:

1. 브라우저 창에 일반적인 Google 로그인 화면이 열립니다.

2. "Google hasn't verified this app" 화면이 표시됩니다. 이는 정상입니다 — Testing 모드의 본인 OAuth 클라이언트가 민감한 범위를 요청하는 것이기 때문입니다. Continue를 클릭하세요(이전 UI: Advanced → Go to [app name] (unsafe)).

3. "Send email on your behalf" 권한을 승인합니다.

4. 브라우저에 *"The authentication flow has completed. You may close this window."*가 표시됩니다.

5. 터미널에 Authorized. Token saved to ...credentials\token.json이 출력됩니다.

2단계에서 대신 Error 403: access_denied / *"has not completed the Google verification process... can only be accessed by developer-approved testers"*가 표시된다면, 본인의 Gmail 주소가 아직 Audience → Test users 목록에 없는 것입니다. 위의 1.4단계로 돌아가세요.

이 작업은 한 번만 하면 됩니다. 이후 server.py는 저장된 토큰을 자동으로 갱신할 뿐, 스스로 브라우저를 다시 열지 않습니다.

4. 토큰 정상 여부 확인(선택 사항이지만 권장)

python -c "from gmail_auth import load_credentials; c = load_credentials(); print('valid:', c.valid); print('scopes:', c.scopes); print('has refresh token:', bool(c.refresh_token))"

valid: True, scopes: ['https://www.googleapis.com/auth/gmail.send'], has refresh token: True가 표시되어야 합니다.

5. Claude Code에 등록하기

claude mcp add gmail-sender --scope user -- python C:\Users\GaneshGupta\gmail-mcp-server\server.py

--scope user는 전역으로 등록합니다. 즉, 명령을 실행한 해당 세션뿐 아니라 이후 이 머신의 모든 Claude Code 세션에서 사용할 수 있게 됩니다. 이미 실행 중인 세션에는 소급 적용되지 않습니다 — MCP 서버는 세션 시작 시 로드되므로, 새 터미널 / 새 claude 세션에서 확인하세요.

확인:

claude mcp list

목록에 gmail-sender가 표시되어야 합니다.

6. 사용 방법

위 등록을 마친 후 아무 Claude Code 세션에서나 자연어로 요청하기만 하면 됩니다:

jane@example.com으로 제목 "Following up", 본문 "..."인 이메일을 보내고 C:\path\to\file.pdf를 첨부해 줘

Claude Code가 send_email 도구를 직접 호출합니다. 세션별 추가 설정은 필요 없습니다.

도구 참조

send_email(to, subject, body, attachments=None, cc=None, bcc=None, html=False)

• to / cc / bcc: 쉼표로 구분된 주소 목록

• attachments: 절대 경로 로컬 파일 경로 목록, 총 15MB 제한(Gmail의 원시 전송 상한은 25MB이며, 원시 파일 15MB는 base64 인코딩 증가분과 헤더를 위한 여유를 확보합니다)

• html: true로 설정하면 일반 텍스트 대신 HTML 본문으로 전송합니다

• 반환값: {status, message_id, thread_id, to, subject, attachment_count}

문제 해결 색인

참고 사항

• credentials/client_secret.json과 credentials/token.json은 gitignore 처리되어 있습니다. 절대 커밋하지 마세요.

• 다른 Gmail 계정으로 보내려면 credentials/token.json을 삭제하고 auth_setup.py를 다시 실행하세요.