gmail-mcp

당신의 AI 비서를 위한 Gmail — 여러 계정을 동시에, 당신이 소유한 서버에서.

日本語版 · 简体中文

gmail-mcp는 Gmail을 Claude 및 기타 MCP 클라이언트와 연결합니다. 메일 검색 및 읽기, 인용된 이력을 포함한 보내기 및 전체 답장, 전달, 첨부 파일 및 인라인 이미지 처리, 드래프트, 라벨, 스레드 관리를 여러 Google 계정에서 동시에 수행할 수 있습니다.

이것은 당신의 Cloudflare Worker에서 원격 서버로 실행되므로, 동일한 연결이 노트북의 Claude Code, 브라우저의 claude.ai, 휴대폰의 Claude에서 응답합니다. 각 연결은 하나의 Google 계정에 로그인하며, Google 갱신 토큰은 당신의 Cloudflare 계정에 남습니다.

사람들이 여기로 오는 데는 두 가지 이유가 있습니다. Claude와 Google에 내장된 Gmail 커넥터는 메일을 읽고 드래프트를 작성할 수 있지만 보낼 수 없으며, 어시스턴트 계정당 하나의 Google 계정만 보유합니다. 보낼 수 있는 서버는 일반적으로 로컬 프로세스입니다 — 책상에서는 괜찮지만 휴대폰에서는 보이지 않습니다.

비교

google_workspace_mcp는 여기서 가장 완성도 높은 프로젝트입니다. Gmail뿐만 아니라 Workspace 전체를 다루며, Gmail 서명을 추가하고 URL에서 직접 첨부 파일을 가져오는데, gmail-mcp는 이 작업을 수행하지 않습니다. shinzo-labs/gmail-mcp는 64개의 도구를 통해 부재중 응답기, 위임자, S/MIME에 접근합니다. 이들은 gmail.settings.* 아래에 있으며, gmail-mcp는 이 범위를 요청하지 않으므로 권한 부여와 관계없이 항상 접근할 수 없습니다.

두 가지 설계 차이가 나머지 대부분을 결정합니다. 호출 인자로 계정을 라우팅하면 하나의 권한이 모든 연결된 사서함에 접근할 수 있는 반면, 사서함을 연결에 바인딩하면 잘못된 인자가 아무것도 도달하지 못하게 합니다. 또한 읽기 시, 로컬 서버는 모든 부분을 UTF-8로 디코딩합니다: ISO-2022-JP 및 Shift_JIS 메일은 깨져서 도착하고, Gmail이 첨부 파일 blob으로 저장한 긴 메시지는 빈 본문으로 반환됩니다.

Related MCP server: Gmail MCP Server

배포하기

약 10분 소요됩니다. Cloudflare 계정, bun, Google 계정이 필요합니다. Cloudflare 계정의 도메인은 선택 사항입니다 — 없으면 Worker가 workers.dev에서 응답합니다.

1 · Google OAuth 클라이언트 생성

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com

Google은 다음 두 단계에 대한 API를 공개하지 않으므로, Cloud 콘솔에서 진행됩니다.:

• OAuth 동의 화면 → 외부(External), 그런 다음 **대상(Audience)**에서 **앱 게시(Publish app)**를 누릅니다. 테스트 모드로 두면 Google은 7일마다 모든 갱신 토큰(refresh token)을 만료시키고 각 연결은 토큰과 함께 사라집니다. 게시하면 앱은 로그인 시 확인되지 않은 앱 경고를 표시하며 최대 100개의 계정을 서비스합니다.

• 사용자 인증 정보(Credentials) → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID → 웹 애플리케이션(Web application), 승인된 리디렉션 URI로 https://<your-host>/callback을 입력합니다. 클라이언트 ID와 비밀번호를 저장해 둡니다.

<your-host>는 Worker가 가리키는 도메인 또는 Worker가 자동으로 부여받는 workers.dev 호스트 이름입니다. 먼저 배포하고 나중에 채워 넣어도 됩니다. Worker가 /에서 제공하는 가이드에 정확한 값이 표시됩니다.

2 · Worker 배포

버튼을 클릭하면 리포지토리가 GitHub 계정에 복사되고, KV 네임스페이스와 Durable Object가 생성되며, 네 가지 비밀값이 요청됩니다. workers.dev에 배포되며, 이후 Settings → Domains & Routes에서 사용자 지정 도메인을 연결할 수 있습니다.

터미널에서 대신 다음과 같이 실행합니다:

git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp
bun install
bun run setup

bun run setup은 응답할 도메인을 묻고, OAUTH_KV 네임스페이스를 생성하거나 재사용하며, 클라이언트 ID와 비밀번호를 입력받고, 쿠키 키를 생성한 후 배포합니다. 처음 두 답변은 wrangler.local.jsonc에 저장되며, 이 파일은 git이 무시합니다. wrangler.jsonc에는 어떤 계정의 네임스페이스나 도메인도 명시되지 않으므로, 클론은 어디서든 배포할 수 있습니다. 단일 비밀값을 교체하기 위해 setup을 다시 실행해도 안전합니다.

3 · 클라이언트 연결

클라이언트 ID와 비밀번호 필드는 비워 둡니다. MCP 클라이언트가 자체적으로 등록합니다.

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Claude Code에서 /mcp를 실행하여 각 연결을 Google 계정에 로그인합니다. claude.ai에서는 Settings → Connectors → Add custom connector에서 동일한 URL을 사용합니다. /mcp/ 뒤에는 단일 세그먼트 레이블을 사용할 수 있으며, 이를 통해 하나의 배포가 여러 클라이언트(두 서버가 URL을 공유하는 것을 거부하는 클라이언트)에 여러 사서함을 제공할 수 있습니다.

배포된 서비스는 https://<your-host>/에서 이 가이드를 제공합니다.

할 수 있는 작업

whoami search_messages get_message get_thread get_attachment

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

메시지는 메일 클라이언트가 보내는 방식과 동일하게 전송됩니다. 일반 텍스트에 HTML 대체 콘텐츠, 파일 첨부 파일, cid:로 참조되는 인라인 이미지가 포함되며, multipart/mixed › multipart/related › multipart/alternative로 중첩됩니다. 제목과 표시 이름은 RFC 2047, 파일 이름은 RFC 2231을 사용하므로 일본어, 중국어, 이모지도 문제없이 전송됩니다.

reply_all은 원본 메일의 Reply-To, From, To, Cc를 읽고, 자신의 주소와 메일을 보내는 모든 주소를 제외한 후, 발신자가 작성한 주소로 답장하며, References 체인을 유지하고, 보내는 부분에 원본을 인용합니다. forward_message는 전달되는 봉투를 재현하며 원본의 파일을 다시 첨부할 수 있습니다.

replyToMessageId와 함께 create_draft를 사용하면 보내기 전에 편집할 수 있는 답장 초안이 작성됩니다. 원본 스레드에 연결되고, In-Reply-To와 References를 유지하며, 답장 전체 수신자와 Re: 제목을 파생하고, 원본을 인용합니다. update_draft는 제공된 필드만 변경합니다. 수신자, 텍스트, 클라이언트에서 수동으로 추가한 파일, 초안이 응답하는 스레드는 다시 읽어와 유지됩니다. base64가 도구 인수에 맞지 않는 파일은 대신 단계적으로 업로드됩니다. stage_attachment_begin은 원시 바이트를 한 번에 curl -T로 받는 업로드 URL을 반환하고, stage_attachment_append는 base64를 청크 단위로 받으며, 모든 attachments 필드는 결과 stagingId를 허용합니다.

읽기 작업은 의도적으로 제한됩니다. 메시지 및 스레드 본문에는 문자 예산이 있고, 전체 응답에는 바이트 상한이 있으며, 첨부 파일은 충분히 작을 때만 인라인으로 반환됩니다. 긴 메일링 리스트 스레드나 큰 파일은 어시스턴트의 컨텍스트를 채우는 대신 잘렸다는 메모와 함께 반환됩니다.

작동 방식

두 개의 OAuth 흐름이 하나의 Worker에서 만납니다. MCP 클라이언트는 Worker에 인증하고, Worker는 사용자를 대신하여 Google에 인증합니다. 어느 쪽도 상대방의 자격 증명을 보유하지 않습니다.

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

사용된 기술

• TypeScript on Cloudflare Workers — Durable Objects는 각각 하나의 MCP 세션을 보유하고, KV는 OAuth 권한 부여를 보유합니다.

• Hono — OAuth 엔드포인트, Google 콜백, /의 설정 페이지 라우팅

• @cloudflare/workers-oauth-provider — MCP 클라이언트가 등록하는 OAuth 2.1 서버

• agents — McpAgent, Durable Objects를 통한 MCP 전송

• @modelcontextprotocol/sdk with Zod — 도구 정의 및 인수 검증

• Bun, Biome, Wrangler — 설치, 테스트, 린트, 배포

Gmail 자체는 REST API에 대해 일반 fetch로 호출됩니다. 공식 googleapis SDK는 Node.js를 가정하고 Worker가 제공해야 하는 것보다 훨씬 많은 양을 포함하므로, 메시지 작성, MIME 파싱 및 토큰 갱신은 대신 src/gmail.ts와 src/utils.ts에 구현되어 있습니다.

엔드포인트

로그인 가능한 사용자

ALLOWED_EMAILS가 결정하며, Google이 확인된 것으로 보고하는 주소와 대조됩니다. 동의 후, 권한 부여가 생성되기 전에 확인됩니다.

각 권한 부여는 인증한 사서함에만 도달하므로, 이 목록을 넓혀도 이미 연결된 사서함에 대한 액세스가 확장되지 않습니다. *로 설정하면 낯선 사람이 배포와 Google 클라이언트 할당량을 사용하여 자신의 메일을 처리할 수 있습니다.

제한

공유 배포가 고갈되는 것을 방지하기 위해 두 가지 상한이 있으며, 둘 다 wrangler.jsonc에 설정됩니다.

Workers Free 요금제에는 추가 상한이 적용됩니다: 호출당 50개의 아웃바운드 요청입니다. 넓은 읽기는 메시지당 하나를 소비하므로, search_messages와 list_drafts는 maxResults를 45 이하로 설정해야 합니다; 그 이상이면 초과분은 결과 대신 메시지별 오류로 반환됩니다. 유료 요금제는 1000을 허용합니다.

둘 중 하나를 올리고 재배포하세요. Cloudflare의 속도 제한기는 빌드 시 바인딩에서 상한을 읽어오므로, 각각의 simple.limit이 이를 변경하는 유일한 곳입니다. 단일 사용자 배포는 둘 다 그대로 둘 수 있습니다 — 일반적인 어시스턴트 사용은 이보다 훨씬 낮은 수준입니다.

보안

셀프 호스팅은 신뢰 문제를 제거하기보다는 이동시킬 뿐이므로, 여기에 모든 것이 위치합니다.

• 토큰은 귀하의 것입니다. 갱신 토큰은 KV 네임스페이스의 OAuth 권한 부여 내에서 암호화됩니다. 세션의 Durable Object는 1시간 유효한 액세스 토큰을 보유하며, MCP 에이전트 프레임워크는 객체가 존재하는 동안 권한 부여의 사본(갱신 토큰 포함)을 보관합니다. 두 저장소 모두 귀하의 Cloudflare 계정에 있으며, 저장 시 암호화됩니다. 메일은 저장되지 않습니다 — 통과만 합니다.

• 하나의 세션, 하나의 사서함. MCP 세션은 이를 연 계정에 바인딩되므로, 한 사서함에 대한 권한 부여는 빌린 세션 ID를 통해 다른 사서함에 작용할 수 없습니다.

• 범위 최소화. gmail.modify는 읽기, 보내기, 라벨 및 휴지통을 포함합니다. 영구 삭제와 gmail.settings.*의 모든 것을 제외하여, 자동 전달 규칙과 필터 유출(고전적인 사서함 백도어)이 도난당한 권한 부여로 할 수 있는 범위 밖에 있도록 합니다. 이와 함께 두 개의 읽기 전용 범위인 userinfo.email과 userinfo.profile이 요청됩니다: 이것들은 허용 목록과 세션 바인딩이 어떤 계정이 로그인했는지 알 수 있는 방법이며, 메일에는 접근하지 않습니다.

• 헤더는 밀반입될 수 없습니다. 모든 발신 헤더 값은 CR, LF 또는 NUL을 포함하면 거부되므로, 어떤 인수도 자체 필드를 벗어나 다른 것을 추가할 수 없습니다 — 예를 들어 제목 줄에 Bcc를 넣는 것과 같습니다. 미디어 유형은 검증되며, 인용된 기록은 HTML 이스케이프 처리됩니다. 이것이 하지 않는 것은 인수 자체를 감시하는 것입니다: bcc는 실제 매개변수이므로, 메시지 본문에 숨겨진 지시에 따라 행동하는 모델이 여전히 이를 채울 수 있으며, 귀하의 클라이언트 승인 프롬프트가 그에 대한 점검 수단으로 남습니다.

• 액세스는 철회될 수 있습니다. ALLOWED_EMAILS를 좁히면 새로운 로그인이 중단됩니다. 단일 계정의 액세스는 myaccount.google.com/connections에서 취소됩니다. Google 클라이언트 시크릿을 순환시키면 모든 권한 부여가 즉시 무효화됩니다.

Worker는 요청을 처리하는 동안 메모리에서 메일을 복호화합니다. 이는 모든 호스팅된 릴레이가 그렇듯이 필수적입니다. 특정 사서함에 대해 이것이 용납되지 않는다면, 해당 사서함에 대해 로컬 MCP 서버를 실행하세요.

테스트 방법

253개의 단위 테스트는 메시지 구성(MIME 중첩, RFC 2047 폴딩, RFC 2231 파일명, CR/LF 거부, base64 래핑), 문자 집합 간 본문 추출, 답장 및 전달 작성, Google 토큰 흐름, 로그인 허용 목록, 로그인의 브라우저 측을 보호하는 CSRF 및 상태 바인딩 검사, 그리고 대역 Gmail에 대한 도구 자체(세션 소유권, 수신자 구성, 첨부 파일 선택, 부분적으로 실패한 읽기가 반환하는 내용)를 다룹니다.

그 외에도 모든 도구는 실제 Gmail 계정에 대해 실행되었으며, 별도의 계정이 도착한 내용을 확인했습니다:

개발

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

질문 및 버그

이슈를 열어주세요 issue.

라이선스

Copyright © 2026 mkpoli. MIT 라이선스에 따라 배포됩니다.

src/workers-oauth-utils.ts는 cloudflare/ai의 remote-mcp-github-oauth 데모에서 파생되었으며, Copyright © 2025 Cloudflare, Inc., MIT 라이선스 하에 사용됩니다. THIRD-PARTY.md를 참조하세요.