multi-gmail-cowork-mcp

하나의 Claude 커스텀 커넥터가 여러 개의 독립적으로 인증된 Gmail 계정을 검색, 읽기, 작성, 전송할 수 있게 해주는 소규모 자체 호스팅 MCP 서버입니다. 누구나 자신의 Google Cloud 프로젝트에 배포할 수 있도록 설계되었으며, 공유 인프라가 전혀 없고 배포별 코드 변경도 필요 없습니다.

Claude Cowork
      |
      v
Your private Multi-Gmail MCP  (your own Cloud Run project)
      |
      +-- Gmail account: "personal"
      +-- Gmail account: "work"
      +-- Gmail account: "billing"
      +-- ...more, added any time via the admin page

Claude에게 다음과 같은 요청을 해보세요:

• "업무 Gmail에서 David가 보낸 이메일을 검색해줘."

• "연결된 모든 Gmail 계정에서 'invoice 4831'을 검색해줘."

• "ACH Works에서 온 최신 이메일을 읽어줘, 어느 계정으로 받았든."

• "어떤 Gmail 계정이 어제 John에게서 이메일을 받았어?"

모든 결과는 출처가 된 계정 별칭과 이메일 주소로 명확하게 표시됩니다. 연결되지 않은 계정이나 인증이 만료된 계정을 요청하면 명확한 오류가 표시됩니다 — 이 서버는 절대 다른 계정을 조용히 대체하지 않습니다.

이것이 아닌 것

Gmail 전용입니다. 캘린더, 드라이브, 문서, 스프레드시트, 연락처는 없습니다. 영구 삭제 도구도 없습니다. 공유 백엔드, 중앙 계정, 원격 측정(telemetry)도 없습니다.

Related MCP server: Gmail MCP

개인정보 보호 모델 — 누가 내 이메일을 볼 수 있나

Google  <->  Your Google Cloud deployment  <->  Claude / Anthropic

• 귀하는 자신의 Google Cloud 프로젝트에, 자신의 Google OAuth 클라이언트와 자신의 Cloud Run 서비스를 사용하여 배포합니다.

• Google은 OAuth 권한을 발급/취소할 수 있으며, 일반적인 OAuth 트래픽만 볼 수 있습니다.

• 귀하의 배포가 Gmail 갱신 토큰이 저장되는 유일한 장소입니다.

• Claude/Anthropic은 Claude가 도구를 호출할 때 도구가 반환하는 내용만 볼 수 있습니다(다른 MCP 도구와 동일) — 그 이상도, 사용하지 않을 때는 아무것도 볼 수 없습니다.

• 이 저장소의 작성자는 귀하의 이메일을 절대 볼 수 없습니다. 공유 서버가 없습니다. 사촌의 배포와 귀하의 배포는 소스 코드 외에는 공통점이 없습니다.

전체 신뢰 경계와 설계 근거에 대한 설명 — 인증이 왜 그렇게 구현되었는지, 이 프로젝트의 알려진 제한 사항을 포함하여 — 은 SECURITY.md를 읽어보세요. 이 README는 그 근거를 반복하지 않습니다.

아키텍처 개요

• 언어/런타임: Node.js 20+에서 TypeScript, 공식 @modelcontextprotocol/sdk와 Google의 google-auth-library 사용.

• 전송 방식: Streamable HTTP(현재 MCP 권장 원격 전송), 무상태(stateless) — 모든 요청이 독립적으로 처리되므로 세션 선호도 없이 Cloud Run에서 깔끔하게 확장됩니다.

• Claude <-> 서버 인증: PKCE/S256을 사용한 MCP OAuth 2.1 인증 코드 흐름, 동적 클라이언트 등록(Dynamic Client Registration), 단기 액세스 토큰, 순환 갱신 토큰, Secret Manager의 배포 로컬 인증 상태.

• 서버 <-> Google 인증: PKCE를 사용한 표준 OAuth 2.0, 연결된 Gmail 계정당 하나의 권한, gmail.modify 범위(읽기, 작성, 전송, 사서함 수정, 영구 삭제 없음).

• 계정 저장: 별칭, 이메일, 갱신 토큰을 담은 작은 JSON 배열을 보관하는 하나의 Google Secret Manager 시크릿. 데이터베이스 없음.

• 관리 UI: HTTP Basic Auth 뒤에 있는 몇 개의 스타일 없는 HTML 페이지 — 계정 연결/연결 해제에 충분한 수준.

사전 요구 사항

• Google 계정과 결제가 활성화된 Google Cloud 프로젝트(부트스트랩은 결제가 연결되지 않은 경우 정확한 결제 페이지를 출력합니다).

• 커스텀 커넥터를 지원하는 Claude 요금제(Cowork/claude.ai 연결용).

• 배포에 필요한 다른 것은 없습니다: Google Cloud Shell에는 이미 gcloud, curl, openssl, jq가 포함되어 있습니다.

비용 및 결제

Cloud Run은 결제가 활성화된 프로젝트가 필요합니다. 이 배포는 개인/소규모 비즈니스용으로 설계되었습니다: 최소 인스턴스 0(유휴 시 0으로 축소) 및 최대 인스턴스 3. 일반적인 사용 — 하루에 몇 번의 검색, 읽기, 전송 — 은 Cloud Run의 Google Cloud 무료 등급(Always Free) 한도 내에 충분히 머물므로, 실제 지속 비용은 $0입니다. 이것은 보장이 아닙니다: 무료 등급을 초과하는 지속적인 요청 폭증은 일반적인 Cloud Run 요금이 발생합니다. 부트스트랩은 지출 전에 알림을 받고 싶다면 선택적 예산 알림 링크를 출력합니다.

원클릭 Cloud Shell 설정(권장)

1. 위의 버튼을 사용하여 이 저장소를 Google Cloud Shell에서 엽니다(또는 GitHub의 Open in Cloud Shell 사용).

2. Cloud Shell이 요청하면 인증하고 다음을 실행합니다:

./scripts/bootstrap.sh

이 스크립트는 프로젝트를 선택하도록 요청하고(또는 생성하고), 결제를 확인하고, 필요한 API를 활성화하고, 전용 Cloud Run 런타임 서비스 계정을 만들고, 필요한 Secret Manager 역할만 할당하고, 모든 시크릿을 생성하고, Cloud Run을 배포하고, PASS/FAIL 검사를 출력합니다. 다시 실행해도 안전합니다: 기존 시크릿, 계정 기록, OAuth 자격 증명, Cloud Run 서비스는 보존됩니다.

이 스크립트는 비밀번호, OAuth 클라이언트 시크릿, 갱신 토큰, 계정 저장소 JSON, MCP OAuth 토큰을 절대 출력하지 않습니다. 시크릿 값은 정확한 바이트로 기록됩니다(후행 개행 자격 증명 버그 없음). 읽기 전용 Cloud Shell 사전 요구 사항 확인에는 ./scripts/bootstrap.sh --check를 사용하세요.

피할 수 없는 Google 브라우저 단계 하나

Google은 범용 웹 OAuth 클라이언트 생성을 위한 안전하고 지원되는 API/CLI 작업을 제공하지 않습니다. 부트스트랩이 요청하면 출력하는 Google Auth Platform 페이지를 열고 다음을 수행하세요:

• 앱을 **외부(External)**로 구성하고, 범위 https://www.googleapis.com/auth/gmail.modify를 추가하고, 테스트 사용자로 사용할 Gmail 주소를 추가하세요.

• 애플리케이션 유형 **웹 애플리케이션(Web application)**으로 OAuth 클라이언트를 만드세요.

• 스크립트가 출력한 정확한 콜백 URI를 입력하세요: https://<your-cloud-run-host>/oauth/google/callback.

• 결과로 나온 클라이언트 ID와 클라이언트 시크릿을 Cloud Shell의 숨겨진 프롬프트에 붙여넣으세요.

Google에서 앱 미검증 경고가 표시되면 개인 배포에서는 정상입니다. 테스트 모드의 7일 제한을 넘어 갱신 토큰을 유효하게 유지하려면 동의 화면을 **프로덕션(In production)**으로 게시하세요. 개인/소규모 배포에는 검증이 필요하지 않습니다.

마지막에 부트스트랩은 관리자 URL, 정확한 Google OAuth 콜백 URL, MCP URL, 다음 사람 작업을 출력합니다. Claude는 지원되는 OAuth 흐름을 통해 MCP 엔드포인트에 인증합니다. 복사하거나 URL에 넣을 정적 커넥터 헤더는 없습니다.

Gmail 계정 연결

1. 부트스트랩이 마지막에 출력한 명령으로 관리자 비밀번호(부트스트랩이 생성하고 절대 출력하지 않음)를 검색하세요:

   gcloud secrets versions access latest --secret=admin-password --project=YOUR_PROJECT_ID

   그런 다음 출력된 관리자 URL을 열고 사용자 이름 admin과 해당 비밀번호로 로그인하세요.

2. personal 또는 work 같은 짧은 별칭을 입력하고 Add Gmail Account를 클릭한 후 Google 인증을 완료하세요. 인증 URL은 consent select_account를 요청하므로 Google은 매번 계정 선택기를 표시합니다. 콜백 후 표시되는 주소는 Google이 실제로 인증한 주소입니다. 별칭 필드에서 가져온 것이 아닙니다.

3. 원하는 만큼 여러 Gmail 계정에 대해 반복하세요. 각 별칭은 독립적이며 모든 결과는 별칭과 확인된 Gmail 주소 모두에 귀속됩니다.

Claude Cowork 연결

Claude에서 Settings → Connectors → Add custom connector를 열고 정확히 다음을 입력하세요:

1. Connector name: Multi Gmail

2. Remote MCP URL: /claude-mcp로 끝나는 출력된 URL

3. OAuth Client ID: 비워 둠(서버가 동적 클라이언트 등록을 지원함)

4. OAuth Client Secret: 비워 둠

/mcp 경로는 기존 클라이언트를 위해 계속 사용할 수 있습니다. 새 Claude 커넥터에는 /claude-mcp를 사용하여 OAuth 리소스 ID가 이전 커넥터 레코드와 독립적이도록 하세요.

Add를 클릭한 다음 Connect를 클릭하세요. Claude는 MCP 인증 메타데이터를 발견하고, 자신을 등록하고, 배포의 Authorize MCP access 페이지를 엽니다. 거기서 사용자 이름 admin과 자신의 admin-password Secret Manager 시크릿에 저장된 관리자 비밀번호로 로그인한 후 승인하세요. Claude는 https://claude.ai/api/mcp/auth_callback의 콜백을 통해 리디렉션되고, OAuth 토큰을 저장하고, 다시 연결합니다. Claude에 Gmail OAuth 클라이언트 ID나 시크릿을 입력하지 마세요 — 그것들은 Google의 Gmail 설정에만 속합니다.

커넥터가 연결된 후 Claude에게 list_accounts를 호출하도록 요청하고, 각 계정에 대해 별칭별 검색을 실행하고, search_all_accounts로 귀속을 확인하세요.

배포 검증

scripts/acceptance_test.mjs는 모든 도구가 자신의 배포에 대해 엔드투엔드로 작동함을 증명합니다 — 계정 격리, 잘못된 별칭에 대한 폴백 없음, 초안, 도착 및 올바른 From ID를 포함한 전송. 실제 원격 클라이언트로서 전체 MCP OAuth 흐름을 수행하며 토큰을 절대 출력하지 않습니다:

MCP_BASE_URL=https://your-service.run.app \
  MCP_ADMIN_PASSWORD='...'   # Secret Manager -> admin-password
  node scripts/acceptance_test.mjs

전송 테스트는 계정 A → 계정 B로 하나, 계정 B → 계정 A로 하나를 보내므로 수신자는 항상 자신이 소유한 계정입니다. 전송을 건너뛰려면 SKIP_SEND=1을 설정하세요.

로컬 개발(선택 사항)

소스 개발 전용으로 Node.js 20+를 설치하고, npm install을 실행하고, .env.example을 .env로 복사하고, TOKEN_STORE=file을 설정하고, npm run dev를 사용하세요. 로컬 Gmail OAuth에는 http://localhost:8080/oauth/google/callback과 같은 별도의 OAuth 클라이언트 콜백이 필요합니다. 프로덕션 시크릿을 재사용하거나 커밋하지 마세요. Windows 사용자는 Cloud Shell 부트스트랩 대신 scripts/setup.ps1과 scripts/deploy.ps1을 사용할 수 있습니다.

계정 재인증 / 연결 해제

이전 읽기 전용 릴리스에서 업그레이드한 후 각 기존 계정은 Needs Gmail permission upgrade로 표시됩니다. /admin을 열고 같은 별칭에 대해 Reauthorize를 클릭한 후 Google의 동의 화면을 완료하세요. 콜백은 해당 별칭의 저장된 갱신 토큰을 교체하기 전에 Google이 실제로 https://www.googleapis.com/auth/gmail.modify를 부여했는지 확인합니다. 그때까지 읽기 도구는 이전 권한으로 계속 작동하고, 쓰기 도구는 명확한 재인증 메시지를 반환합니다. 다른 별칭이 사용되는 일은 없습니다.

액세스를 제거하려면 계정 옆의 Disconnect를 클릭하세요. 이렇게 하면 Google의 권한이(최선의 노력으로) 취소되고 자격 증명 저장소에서 즉시 제거됩니다 — 이후 해당 별칭이 요청되면 Claude는 조용한 폴백 없이 명확한 "연결되지 않음" 오류를 받게 됩니다.

Google 측에서 액세스를 취소한 후 같은 별칭을 다시 연결하려면 같은 별칭으로 Connect account를 사용하세요 — Google 인증이 성공한 후에만 이전 레코드를 덮어씁니다.

쓰기 도구 및 안전

배포된 서버는 create_draft와 send_email을 노출합니다. 둘 다 명시적인 연결 계정 별칭이 필요하며 다른 계정으로 폴백하지 않습니다. send_email은 항상 선택한 Gmail ID에서 전송하며 결과에는 확인된 주소가 포함됩니다. 도구는 더 넓은 mail.google.com 범위가 아닌 gmail.modify를 사용하며 영구 삭제 도구는 없습니다. Claude 커넥터 권한은 읽기 도구를 자동으로 허용하면서 create_draft와 send_email은 **승인 필요(Needs approval)**로 유지해야 합니다.

업데이트 및 순환

• 배포 업데이트: 소스를 변경한 후 또는 새 시크릿 버전을 적용하려면 ./scripts/bootstrap.sh를 다시 실행하거나(멱등적 — 계정, 토큰, OAuth 클라이언트 보존) Windows에서는 scripts/deploy.ps1을 실행하세요. 기존 Gmail 연결과 Claude 커넥터는 영향을 받지 않습니다.

• 관리자 비밀번호 순환: admin-password에 새 Secret Manager 버전을 추가하고 재배포하세요. 기존 Claude 커넥터 토큰은 유효하게 유지됩니다(관리자 비밀번호에서 파생되지 않음). 향후 MCP 동의 승인만 새 비밀번호를 사용합니다.

• oauth-state-secret 순환: 이 시크릿은 모든 MCP OAuth 토큰에 서명하므로, 순환하면 Claude 커넥터의 기존 토큰이 무효화됩니다 — 이후 Claude를 다시 연결하세요. 보류 중인 Gmail 연결 상태 토큰(10분 수명)도 무효화됩니다. 연결된 Gmail 계정은 영향을 받지 않습니다.

• Gmail 계정의 권한 순환: 관리자 페이지에서 별칭을 다시 연결하세요(계정 재인증 / 연결 해제 참조).

모든 것을 삭제하는 방법

• Gmail 액세스 제거: /admin에서 각 계정의 연결을 해제하거나, https://myaccount.google.com/permissions에서 직접 액세스를 취소합니다.

• 배포 해체:

  gcloud run services delete multi-gmail-mcp --region us-central1
  gcloud secrets delete mcp-oauth-state admin-password oauth-state-secret google-client-id google-client-secret gmail-mcp-accounts
  gcloud iam service-accounts delete multi-gmail-mcp-run@YOUR_PROJECT_ID.iam.gserviceaccount.com

• OAuth 클라이언트 삭제: Cloud Console -> APIs & Services -> Credentials -> OAuth 클라이언트 ID를 삭제하고, 선택적으로 OAuth 동의 화면 구성을 삭제합니다.

• 또는 가장 간단한 방법: Google Cloud 프로젝트 전체를 삭제합니다.

문제 해결

• "계정을 다시 연결해야 함" 오류: 저장된 refresh token이 Google에서 거부되었습니다(취소, 만료 또는 동의 화면이 "Testing" 상태에 머물러 있음 — 아래 참조). /admin에서 다시 연결하세요.

• Refresh token이 약 7일 후 계속 만료됨: OAuth 동의 화면이 여전히 "Testing" 게시 상태입니다. "In production"으로 게시하세요(3단계 참조) — 검증되지 않은 상태로 두어도 개인 사용에는 문제없습니다.

• Claude가 커넥터에 연결할 수 없음 / 연결이 조용히 실패함: 서비스 URL이 다른 호스트로의 리디렉션 없이 일반 HTTPS로 확인되는지 확인한 다음, Claude에서 /claude-mcp로 끝나는 MCP URL을 열고 Connect를 다시 클릭하세요. 서버는 액세스 토큰 없이 호출될 때 OAuth 메타데이터와 401 챌린지를 반환해야 합니다. 정적 요청 헤더는 필요하지 않습니다.

• gcloud run deploy가 API 미활성화로 실패: scripts/setup.ps1을 다시 실행하거나, gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com gmail.googleapis.com iam.googleapis.com을 실행하세요.

• 로컬 개발 환경에서 HTTPS로 Google에 연결할 수 없음(인증서 오류): 이는 거의 항상 로컬 머신 문제입니다(TLS 가로채기를 수행하는 회사 프록시 또는 바이러스 백신). 이 프로젝트의 버그가 아닙니다 — 머신의 신뢰할 수 있는 루트 인증서를 확인하세요.

Google OAuth Testing과 장기 사용

Google Cloud OAuth 클라이언트는 Testing 게시 상태로 시작합니다. Testing 상태에서는 민감/제한 범위(gmail.modify 포함)에 대한 refresh token이 사용자가 아무리 적더라도 7일 후 만료됩니다. 그대로 두면 매주 조용히 커넥터가 중단됩니다.

해결책은 Google 검증(공개 SaaS를 위한 수개월 프로세스)이 아닙니다. 더 간단합니다: Publish app을 클릭하여 동의 화면을 In production으로 이동하세요. gmail.modify만 요청하고 총 연결된 Google 계정이 100개 미만인 앱의 경우, Google 자체 문서에서 완전히 지원되는 개인/소규모 사용 사례로 취급합니다 — 검증이 필요 없습니다. 유일한 가시적 효과는 새로 연결된 각 계정이 동의를 부여하기 전에 일회성 "Google hasn't verified this app" 클릭 통과 경고를 보는 것입니다. 이 경고는 예상된 것이며, 잘못 구성되었다는 의미가 아닙니다. 기본 규칙 및 출처는 SECURITY.md를 참조하세요.

저장소 구조

src/            TypeScript source (server, MCP tools, admin/setup UI, OAuth flows)
scripts/        bootstrap.sh (Cloud Shell), setup.ps1/deploy.ps1 (Windows),
                acceptance_test.mjs (verify any deployment end-to-end)
.env.example    Local-dev configuration template (placeholders only)
SECURITY.md     Trust model, design rationale, known limitations

라이선스

MIT — LICENSE 참조.