Google Workspace MCP

왜 쓰나요

핵심 기능

서버 하나에 12개 서비스: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script, Custom Search
단계별 도구 세트(core / extended / complete)로 도구 목록을 간결하게 유지
멀티유저 bearer-token 모드를 위한 OAuth 2.0 + 2.1 지원
Docker / Kubernetes를 위한 stateless 모드
암호화된 로컬 token 캐시; 선택적 GCS 기반 credential 저장

라이브 데모

실제 사용 모습

google-workspace-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace-mcp",
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "workspace-mcp",
          "--tool-tier",
          "core"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add google-workspace-mcp -- uvx workspace-mcp --tool-tier core

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Google Workspace MCP

Claude를 어시스턴트로 활용해 Gmail 받은편지함 제로 달성

👤 읽지 않은 이메일이 200개 이상인 분 ⏱ ~25 min beginner

언제 쓸까: 월요일 아침, 받은편지함이 벽처럼 쌓여 있을 때.

사전 조건

Google Cloud OAuth 클라이언트 — console.cloud.google.com에서 OAuth 2.0 credential을 생성하고 client_secret.json을 다운로드
서버 설치 — uvx workspace-mcp --tool-tier core (첫 호출 시 브라우저에서 OAuth 창이 열림)

흐름

받은편지함 분류

Use google-workspace-mcp. List unread mail from the last 7 days. Bucket into: action-required, FYI, newsletters, automated.✓ 복사됨

→ 버킷별 메일 수와 제목 샘플
중요도 낮은 버킷 자동 보관

Archive everything in newsletters + automated. Don't touch action-required.✓ 복사됨

→ N개 보관됨, action-required 0개 영향
답장 초안 작성

For each action-required email, draft a 2-line reply in my voice. Save as drafts, don't send.✓ 복사됨

→ Gmail에 초안 저장됨; 직접 수정 후 발송

결과: 받은편지함 20개 미만으로 정리, 답장 초안 작성 완료 — 최종 검토 및 발송은 사용자가 직접 담당.

함정

Gmail 전체 권한을 부여했다가 후회 — --tool-tier core 사용 — extended로 선택하기 전까지 send_email 도구는 없음

함께 쓰기: filesystem

Calendar + Docs 활동으로 주간 상태 보고서 자동 생성

👤 주간 업데이트를 작성해야 하는 개발자와 매니저 ⏱ ~10 min beginner

언제 쓸까: 금요일 오후, 이번 주에 무엇을 했는지 기억이 안 날 때.

흐름

캘린더 조회

Use google-workspace-mcp. List meetings I attended Mon–Fri this week (skip declined). For each, give 1-line context.✓ 복사됨

→ 미팅별 간략한 맥락이 포함된 시간순 목록
문서 활동 조회

List Drive docs I edited or commented on this week. Group by project.✓ 복사됨

→ 프로젝트별로 묶인 문서 목록 및 수정/댓글 수
업데이트 초안 작성

Combine into a 6-bullet weekly update — what I shipped, what's blocked, what's next.✓ 복사됨

→ Slack/이메일 발송 준비 완료 초안

결과: 30분이 아닌 3분 만에 완성된 주간 업데이트, 실제 아티팩트 기반.

함정

반복적인 1:1 미팅이 보고서를 어지럽힘 — 이벤트 제목 패턴이나 참석자 수로 필터링 — Claude에게 기본적으로 반복 1:1 제외 요청

지저분한 Sheets에서 구조화된 데이터 추출 후 결과 쓰기

👤 스프레드시트를 주로 사용하는 운영, 재무 담당자 ⏱ ~20 min intermediate

언제 쓸까: 자유 텍스트 설명이 1000행 있는 시트를 분류해야 할 때.

흐름

범위 읽기

Use google-workspace-mcp. Read column B from Sheet 'Q4 expenses' — 1000 rows of vendor descriptions.✓ 복사됨

→ 행 로드됨; 샘플 표시
분류

Categorize each row into: SaaS, hardware, travel, services, other. Show distribution first.✓ 복사됨

→ 분포 표; 예시 데이터 확인
결과 쓰기

Write categories into column F. Add a header. Don't touch other columns.✓ 복사됨

→ 시트 업데이트됨; 샘플 수동 확인

결과: 시트에 분류된 데이터 저장, 채팅에 감사 추적 기록.

함정

Claude가 중요한 열을 덮어씀 — 대상 열을 명시적으로 지정; 대량 쓰기 전 몇 개 셀 확인

캘린더 일정에서 미팅 준비 문서 자동 생성

👤 연속 미팅이 많은 분 ⏱ ~15 min intermediate

언제 쓸까: 내일 미팅이 5개인데 아무것도 준비 안 됐을 때.

흐름

내일 일정 스캔

Use google-workspace-mcp. List tomorrow's meetings with attendees and any attached docs.✓ 복사됨

→ 미팅별 참석자 + 링크된 문서 블록
브리핑 문서 생성

For each, create a Doc 'Prep — <meeting title>' summarizing attached docs + suggesting 3 questions to ask.✓ 복사됨

→ /Meeting prep/ 폴더에 N개 Doc 생성됨

결과: 즉흥이 아닌 준비된 상태로 각 미팅에 참석.

함정

외부 참석자가 준비 문서를 볼 수 없지만 공유된 제목이 의도를 노출할 수 있음 — 비공개 준비 폴더 사용; 제목은 '<민감한 거래명>' 대신 'Prep — <주제>'로

조합

다른 MCP와 조합해 10배 효율

google-workspace-mcp + filesystem

오프라인 편집이나 git 추적을 위해 Drive 문서를 로컬에 동기화

Pull all docs in /weekly-updates/ from Drive into ./drive-mirror/ as markdown.✓ 복사됨

google-workspace-mcp + github

GitHub와 Google Doc 간 릴리스 노트 미러링

Take the latest GitHub release notes and append them to the 'Release log' Google Doc.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
search_gmail	query: str (Gmail search syntax), max_results?	자연어 조건에 맞는 이메일 검색	1 Gmail API call
send_email	to, subject, body, cc?, bcc?	extended/complete 티어 전용 — 확인 없이 자동 발송 금지	1 API call
list_calendar_events	calendar_id, time_min, time_max	특정 날짜 범위의 이벤트 조회	1 Calendar API call
read_sheet_range	spreadsheet_id, range (A1 notation)	시트에서 셀 데이터 가져오기	1 Sheets API call
write_sheet_values	spreadsheet_id, range, values[][]	계산된 데이터로 시트 범위 업데이트	1 API call
create_doc	title, content (markdown)	채팅 결과물로 새 문서 생성	1 Docs API call
search_drive	query, mime_type?	이름/내용으로 파일 검색	1 Drive API call

비용 및 제한

운영 비용

API 쿼터: Gmail: 250 quota units/user/sec; Calendar: 500 req/100sec; Sheets: 300 req/min/user
호출당 토큰: 호출 방식에 따라 200–4000 (이메일 전체 본문 vs 메타데이터)
금액: 개인 Google 계정은 무료; Workspace 조직은 관리자 제한이 있을 수 있음
팁: Forms/Slides/Apps-Script가 실제로 필요하지 않으면 --tool-tier core 사용 — 도구 수가 줄면 시스템 prompt도 작아짐

보안

권한, 시크릿, 파급범위

최소 스코프: gmail.readonly calendar.readonly drive.readonly

자격 증명 저장: 기본적으로 암호화된 로컬 token 캐시; 호스팅 환경에는 선택적으로 GCS 사용

데이터 외부 송신: googleapis.com으로 직접 전송 — 서드파티 중계 없음

절대 부여 금지: gmail.send (자동 발송 위험을 충분히 이해하기 전까지) drive (전체 읽기/쓰기 권한)

OAuth 2.0 + 2.1 모두 지원; 별도 confidential client 설정이 없다면 PKCE public client 선택

문제 해결

자주 발생하는 오류와 해결

OAuth 콜백 실패 / 브라우저가 열리지 않음

OAUTH_REDIRECT_PORT를 열린 포트로 설정하고 재실행; headless 환경에서는 device-flow 모드 사용

확인: lsof -i :8080 to confirm port free

403 insufficient_permissions

누락된 scope로 재인증; Google Cloud Console에서 OAuth 클라이언트에 해당 scope가 허용됐는지 확인

확인: Decode token at oauth2.googleapis.com/tokeninfo to see granted scopes

Workspace 관리자가 OAuth 클라이언트 차단

관리자에게 클라이언트 ID를 신뢰할 수 있는 앱 목록에 추가 요청, 또는 테스트용 개인 Google 계정 사용

대량 작업 중 할당량 초과

백오프 추가; 서버가 Retry-After 헤더를 따르지만 대량 루프에서 초당 제한에 걸릴 수 있음

확인: Watch for HTTP 429 in logs

대안