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: littlebird-mail

배포하기

약 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

다음 두 단계는 API가 아니라 Cloud 콘솔에서 진행됩니다:

• OAuth 동의 화면 → 외부, 그런 다음 대상 고객 아래에서 앱 게시를 누릅니다. 테스트 모드로 두면 Google은 7일마다 모든 리프레시 토큰을 만료시키고 각 연결은 토큰과 함께 죽습니다. 게시하면 앱은 로그인 시 확인되지 않은 앱 경고를 표시하고 최대 100개의 계정을 제공합니다.

• 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID → 웹 애플리케이션, 승인된 리디렉션 URI로 https://<your-host>/callback을 사용합니다. 클라이언트 ID와 비밀번호를 보관하세요.

<your-host>는 Worker를 가리키는 도메인 또는 그렇지 않으면 얻는 workers.dev 호스트 이름입니다. 먼저 배포하고 나중에 이 값을 채우는 것도 작동합니다. Worker가 /에서 제공하는 가이드에 정확한 값이 표시됩니다.

2 · Worker 배포

버튼은 저장소를 GitHub 계정에 복사하고, KV 네임스페이스와 Durable Object를 생성하며, 네 가지 비밀을 요청합니다. workers.dev에 배포합니다. 사용자 지정 도메인은 나중에 설정 → 도메인 및 경로에서 연결합니다.

터미널에서 대신:

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에서는 설정 → 커넥터 → 사용자 지정 커넥터 추가에서 동일한 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를 가정하고 Worker가 제공해야 하는 것보다 훨씬 많은 것을 포함하므로 메시지 구성, MIME 파싱, 토큰 새로 고침은 대신 src/gmail.ts와 src/utils.ts에 있습니다.

엔드포인트

로그인할 수 있는 사람

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

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

제한

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

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

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

보안

셀프 호스팅은 신뢰 문제를 제거하는 것이 아니라 이동시킬 뿐이므로, 여기에 모든 것이 어디에 있는지 정리합니다.

• 토큰은 사용자 소유로 유지됩니다. 리프레시 토큰은 KV 네임스페이스의 OAuth grant 내부에 암호화되어 저장됩니다. 세션의 Durable Object는 1시간 동안 유효한 액세스 토큰을 보유하며, MCP 에이전트 프레임워크는 객체가 살아있는 동안 grant의 사본(리프레시 토큰 포함)을 그곳에 보관합니다. 두 저장소 모두 사용자 자신의 Cloudflare 계정이며, 저장 시 암호화됩니다. 메일은 저장되지 않습니다 — 통과만 할 뿐입니다.

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

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

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

• 접근을 철회할 수 있습니다. ALLOWED_EMAILS를 좁히면 새 로그인이 중단됩니다. 단일 계정의 접근은 myaccount.google.com/connections에서 철회됩니다. Google 클라이언트 시크릿을 교체하면 모든 grant가 한 번에 무효화됩니다.

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 License에 따라 배포됩니다.

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