google_workspace_mcp MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

11개 서비스를 하나의 서버에서 지원합니다: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script
도구 계층(core/extended/complete)으로 도구 목록을 축소하여 프롬프트 비용을 절감할 수 있습니다.
자신의 Google Cloud 자격증명을 통한 OAuth 2.0 지원 — 제3자 브로커 불필요
stdio + HTTP MCP 전송을 지원합니다
긴 문서/시트 읽기를 위한 스트리밍 출력 지원

라이브 데모

실제 사용 모습

google-workspace.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace",
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace": {
      "command": {
        "path": "uvx",
        "args": [
          "google_workspace_mcp"
        ]
      }
    }
  }
}

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

claude mcp add google-workspace -- uvx google_workspace_mcp

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

사용 사례

실전 활용법: google_workspace_mcp

AI 라벨과 임시 저장으로 받은편지함을 정리하는 방법

👤 지식 근로자, 경영진 ⏱ ~20 min intermediate

언제 쓸까: 월요일 아침이나 휴가 후 받은편지함이 가득 찼을 때

사전 조건

Gmail API가 활성화된 Google Cloud 프로젝트 — console.cloud.google.com > APIs > Gmail API > Enable
OAuth 2.0 데스크톱 자격증명 — Credentials > Create OAuth client > Desktop. GOOGLE_OAUTH_CLIENT_ID와 _SECRET 환경 변수 설정

흐름

지난주 읽지 않은 메시지 가져오기

지난 7일간의 읽지 않은 Gmail 메시지를 검색합니다. 발신자 카테고리(팀, 외부, 판매처, 뉴스레터)별로 그룹화합니다.✓ 복사됨

→ 그룹별 개수 + 미리보기 라인
뉴스레터 자동 라벨 지정 + 보관

뉴스레터 버킷의 메시지에 'newsletter' 라벨을 지정하고 보관합니다.✓ 복사됨

→ 보관된 개수, 스레드 ID
상위 5개 중요 스레드에 대한 회신 임시 저장

상위 5개 중요 스레드(클라이언트 요청, 차단, 의사결정 필요)에 대해 간결한 회신을 임시 저장합니다. 전송하지 마세요 — 임시 저장만 합니다.✓ 복사됨

→ Gmail에 표시된 5개 임시 저장 메시지

결과: 받은편지함 20개 이하, 검토 및 전송할 준비가 된 임시 저장 메시지

함정

AI가 회신을 임시 저장하는 대신 전송합니다 — 항상 프롬프트에 'draft only'라고 명시합니다. 신뢰할 수 없는 세션에서는 send_gmail_message를 비활성화합니다.

함께 쓰기: notion

내일 일정에서 모든 회의를 준비하는 방법

👤 연속 회의가 있는 모든 사람 ⏱ ~15 min beginner

언제 쓸까: 바쁜 날 전 업무 마감 시간에

흐름

내일 일정 나열하기

내일의 일정을 가져옵니다. 각 일정에 대해 참석자와 회의 제목을 표시합니다.✓ 복사됨

→ 일정의 시간표
각 회의마다 연결된 문서 및 최근 이메일 찾기

안건 링크가 있는 모든 회의에 대해 문서를 열고 요약합니다. 각 참석자에 대해 마지막 이메일 스레드를 표시합니다.✓ 복사됨

→ 회의별 요약
하나의 문서로 정리하기

회의별 섹션이 있는 'Prep 2026-04-15' 문서를 만듭니다.✓ 복사됨

→ 반환된 문서 URL

결과: 커피를 마시면서 훑어볼 수 있는 하나의 준비 문서

함정

외부 참석자의 이메일에는 개인식별정보가 포함되어 있으며, LLM 공급자에게 전송됩니다 — 개인정보 보호가 중요하다면 프롬프트에서 이름만 유지합니다.

함께 쓰기: notion

Google Sheet를 에이전트용 읽기/쓰기 데이터 소스로 변환하는 방법

👤 Sheet에서 비즈니스 프로세스를 운영하는 운영팀 ⏱ ~15 min intermediate

언제 쓸까: 아직 실제 데이터베이스로 마이그레이션하고 싶지는 않지만 AI가 질문에 답하고 이벤트를 기록하길 원할 때

흐름

Sheet 레이아웃 설명하기

스프레드시트 1AbC... 의 'Orders' 탭을 읽고 스키마를 알려줍니다.✓ 복사됨

→ 유형이 포함된 열 목록
질문에 답하기

read_sheet_values를 사용하여 3월에 $1000 이상이었던 주문의 수는 몇 개입니까?✓ 복사됨

→ 수치 답변 + 참고된 셀
행 추가하기

새 행을 추가합니다: 오늘 날짜, customer=acme, amount=1200, status=pending.✓ 복사됨

→ 추가된 행 인덱스

결과: 채팅을 떠나지 않고도 임시 분석 + 로깅

함정

수식은 쓰기 시 재계산되며 중요한 셀을 덮어쓸 수 있습니다 — 데이터를 추가할 때 범위 쓰기가 아니라 append_table_rows를 사용합니다.

함께 쓰기: filesystem

마크다운 템플릿으로 Google Doc를 생성하는 방법

👤 제안서, 보고서 또는 템플릿 문서를 생성하는 모든 사람 ⏱ ~10 min beginner

언제 쓸까: Google API를 배우지 않고도 서식 있는 Docs 출력(표, 제목)을 원할 때

흐름

마크다운으로 초안 작성

[brief]를 기반으로 ACME를 위한 클라이언트 제안서를 작성합니다. 마크다운으로 출력합니다.✓ 복사됨

→ 마크다운 초안
Doc으로 변환하기

'ACME Proposal 2026-04'라는 제목의 새 Google Doc를 만듭니다. create_doc을 사용한 후 batch_update_doc을 사용하여 서식을 유지합니다.✓ 복사됨

→ Doc URL

결과: 공유할 수 있는 적절한 형식의 Doc

함정

create_doc은 일반 텍스트만 허용합니다 — 서식을 위해서는 batch_update가 필요합니다 — 서식 있는 문서의 경우 항상 2단계 흐름을 사용합니다.

조합

다른 MCP와 조합해 10배 효율

google-workspace + notion

Notion에 회의 준비 문서를 미러링하여 팀 가시성 확보

오늘의 각 회의에 대해 Google Doc 안건을 'Meeting Notes' 아래 날짜를 제목으로 하는 새 Notion 페이지로 복사합니다.✓ 복사됨

google-workspace + filesystem

Drive 폴더를 로컬 디스크로 백업으로 내보내기

Drive 폴더 'Client Contracts 2025'의 모든 파일을 /backups/drive/contracts-2025/로 다운로드합니다.✓ 복사됨

google-workspace + github

GitHub 이슈를 달력 스탠드업과 교차 참조

10am 스탠드업 전에 내게 할당된 열린 GitHub 이슈를 나열하고 요약을 오늘의 스탠드업 이벤트 설명에 첨부합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
search_gmail_messages	query: str, max_results?: int	발신자, 제목, 날짜로 메시지 찾기	Gmail API 1회 호출
draft_gmail_message	to, subject, body, thread_id?	AI 워크플로우에서는 전송보다 임시 저장을 선호합니다	API 1회 호출
send_gmail_message	to, subject, body	사용자가 명시적으로 전송을 ��청할 때만	API 1회 호출(되돌릴 수 없음)
get_events	calendar_id?, time_min, time_max	시간 범위 내 이벤트 가져오기	Calendar API 1회 호출
manage_event	action, event_id?, summary?, attendees?, time?	이벤트 생성/업데이트/삭제	API 1회 호출
read_sheet_values	spreadsheet_id, range	셀 범위 읽기	Sheets API 1회 호출
append_table_rows	spreadsheet_id, table_id, rows	수식을 덮어쓰지 않으면서 안전하게 추가	Sheets API 1회 호출
create_doc	title, content?	새 문서 시작하기	Docs API 1회 호출
batch_update_doc	doc_id, requests[]	create_doc 후 서식 적용	Docs API 1회 호출(배치)
search_drive_files	query, max_results?	이름/소유자로 파일 찾기	Drive API 1회 호출

비용 및 제한

운영 비용

API 쿼터: Gmail: 사용자당 초당 250 쿼터 단위. Sheets: 사용자당 분당 300회 읽기. Drive: 사용자당 100초당 1000회 쿼리.
호출당 토큰: 'complete' 계층의 도구 목록은 매우 큽니다(~100개 도구). 비용을 절감하려면 'core' 계층을 사용합니다.
금액: Google 계정으로 무료
팁: --tool-tier core로 실행하고 실제로 Slides/Forms/Script가 필요할 때만 extended로 전환합니다.

보안

권한, 시크릿, 파급범위

최소 스코프: 실제로 사용하는 서비스의 범위만 부여합니다(예: gmail.readonly, calendar.readonly)

자격 증명 저장: env의 GOOGLE_OAUTH_CLIENT_ID/_SECRET; 디스크에 지속되는 새로고침 토큰

데이터 외부 송신: 문서/이메일 콘텐츠는 MCP 서버를 통해 선택한 LLM 공급자로 전송됩니다

절대 부여 금지: 전송이 필요하지 않으면 gmail.send 부여 금지 drive.file로 충분하면 drive(전체) 부여 금지 관리자 범위 부여 금지

OAUTHLIB_INSECURE_TRANSPORT=1은 localhost 개발용입니다 — 호스팅된 인스턴스에서 절대 설정하지 마세요.
데스크톱 OAuth 클라이언트는 프로덕션 웹 배포에 사용할 수 없습니다. 웹 클라이언트를 사용하세요.

문제 해결

자주 발생하는 오류와 해결

invalid_grant / 토큰이 만료되었거나 취소됨

캐시된 토큰 파일을 삭제하고 인증 흐름을 다시 실행합니다.

확인: ls ~/.config/google_workspace_mcp/tokens

403 권한 부족

필요한 범위로 다시 동의합니다 — 저장된 토큰에 아직 없습니다.

API 활성화되지 않음

Google Cloud Console에서 프로젝트의 특정 API(예: Docs API)를 활성화합니다.

사용자의 쿼터 초과

Gmail과 Sheets에는 분당 제한이 있습니다. 배치 읽기를 수행하고 지수 백오프를 사용하여 재시도합니다.

대안

google_workspace_mcp 다른 것과 비교

대안	언제 쓰나	단점/장점
Official Gmail MCP (Anthropic remote)	Anthropic 호스팅 OAuth를 셋업 없이 원할 때	Gmail만 지원; Drive/Docs/Sheets 미지원
zapier MCP	이미 Zapier를 사용 중이고 설정 없이 원할 때	호출당 비용 발생; 지연 시간 증가

google_workspace_mcp