GWS CLI로 구글 전체를 클로드 코드에 연결

초등학생도 따라할 수 있는 완전 가이드

지메일 · 캘린더 · 드라이브 · 독스 · 시트 · 슬라이드 — 명령어 한 줄이면 됩니다

2026년 3월, 구글이 자기 서비스 전체를 AI에게 열어 버렸습니다. 지메일, 캘린더, 스프레드시트, 슬라이드, 구글 독스까지 하나만 설치하면 클로드 코드에서 전부 쓸 수 있게 된 겁니다. 그 열쇠가 바로 GWS CLI(Google Workspace Command Line Interface)입니다.

이 글은 컴퓨터에 대해 잘 모르는 분도 마치 손가락을 직접 움직여 주듯 따라할 수 있도록 모든 과정을 빠짐없이 담았습니다.

제1부 GWS CLI가 무엇이고 왜 필요한가

1. 터미널 창

카카오톡으로 친구에게 메시지를 보내듯, 컴퓨터에게도 텍스트로 명령을 보낼 수 있습니다. 그 창이 터미널입니다. AI는 손쉽게 텍스트 명령어는 입력해 넣을 수 있습니다. 구글은 핵심 워크스페이스 서비스인 지메일, 드라이브, 독스, 시트, 캘린더를 터미널에서 실행할 수 있는 배시 명령어로 감싸 버렸습니다. 인증은 한 번만 하면 되고, 출력은 스크립팅에 적합한 구조화된 JSON 형태로 나옵니다.

2. 기존 방식과의 차이

API나 MCP를 개별적으로 쓰려면 지메일 따로, 드라이브 따로, 캘린더 따로 각각 연결하고 인증하고 설정해야 했습니다. OAuth2와 씨름하는 파이썬 스크립트를 짜거나, 복잡한 권한의 서비스 계정을 설정하거나, 구글이 API 응답 형식을 바꿀 때마다 망가지는 재피어(Zapier) 자동화를 연결하곤 했습니다. GWS CLI 하나만 설치하면 이 모든 것이 해결됩니다. 만능 USB 포트 같은 존재입니다.

3. GWS CLI가 특별한 네 가지 이유

•자동 업데이트 — GWS는 고정된 명령어 목록을 탑재하지 않습니다. 구글의 디스커버리 서비스(Discovery Service)를 런타임에 읽어서 전체 명령어 체계를 동적으로 구축합니다. 구글 워크스페이스가 API 엔드포인트나 메서드를 추가하면 GWS가 자동으로 반영합니다.

•MCP 서버 내장 — gws mcp -s drive,gmail,calendar 명령을 실행하면 CLI가 MCP 서버를 시작하며, 워크스페이스 API를 MCP 호환 클라이언트(클로드 코드, VS Code 등)가 호출할 수 있는 구조화된 도구로 노출합니다.

•100개 이상의 에이전트 스킬 — 이메일 요약, 답장 초안 작성, 파일 검색, 스프레드시트 자동 업데이트, 문서 작성까지 실무 워크플로우가 이미 내장되어 있고, 지메일·드라이브·독스·캘린더·시트를 위한 50개의 큐레이팅된 레시피가 포함되어 있습니다.

•보안 — 자격 증명은 AES-256-GCM으로 암호화되어 저장되며, 키는 OS 키링(macOS Keychain, Windows Credential Manager)에 보관됩니다.

4. 공식 제품이 아니라는 점

이 프로젝트는 구글의 공식 제품이 아닙니다. v1.0을 향해 한창 개발 중이라 호환성이 깨지는 변경이 생길 수 있다는 점은 감안해야 합니다. 다만 구글 클라우드 인물들이 직접 소개했고, 구글 AI 및 워크스페이스 릴리스로 널리 보도되었습니다. 2026년 3월 출시 이후 Rust로 작성된 오픈소스 도구로서 Apache 2.0 라이선스 아래 공개되어 있습니다.

제2부 사전 준비 — 필요한 것들 확인하기

1. Node.js 설치 확인

GWS CLI는 npm으로 설치합니다. Node.js가 먼저 깔려 있어야 합니다.

맥(macOS)에서 확인하는 법

(1) 화면 오른쪽 위 돋보기(Spotlight)를 클릭하고 "터미널"을 입력합니다.

(2) 터미널이 열리면 아래 명령어를 입력하고 엔터를 칩니다.

(3) v18.0.0 이상의 숫자가 나오면 설치되어 있는 겁니다.

(4) "command not found"라고 나오면 Node.js를 설치해야 합니다.

Node.js가 없다면 설치하기

(1) 브라우저에서 https://nodejs.org 에 접속합니다.

(2) LTS(장기 지원) 버전의 초록색 버튼을 클릭해서 다운로드합니다.

(3) 다운로드된 파일을 더블클릭하고, "계속" 버튼만 누르면 설치가 완료됩니다.

(4) 터미널을 닫았다가 다시 열고 node --version을 입력해서 확인합니다.

윈도우에서 확인하는 법

(1) 키보드에서 윈도우 키를 누르고 "PowerShell"을 검색해서 실행합니다.

(2) node --version을 입력합니다.

(3) 없으면 위와 같은 방법으로 https://nodejs.org 에서 설치합니다.

2. VS Code 설치

(1) https://code.visualstudio.com 에 접속합니다.

(2) 운영체제에 맞는 버전을 다운로드해서 설치합니다.

(3) 한글 모드를 원하면 왼쪽 사이드바의 네모 블록 아이콘(확장)을 클릭하고, "Korean Language Pack"을 검색해서 설치합니다.

3. 클로드 코드를 VS Code에 연결하기

(1) VS Code 왼쪽 사이드바에서 네모 블록 아이콘(확장, Extensions)을 클릭합니다.

(2) 검색창에 "Claude"를 입력합니다.

(3) "Claude" 확장을 찾아서 "Install" 버튼을 누릅니다.

(4) 설치가 끝나면 왼쪽에 클로드 아이콘이 나타납니다. 클릭합니다.

(5) 오른쪽 AI 패널에 로그인 화면이 뜹니다. 주황색 버튼을 클릭해서 클로드 계정으로 연결합니다.

(6) "Git을 설치하라"는 문구가 뜨면 https://git-scm.com 에서 Git을 설치한 뒤 VS Code를 재시작합니다.

4. 작업 폴더 만들기

(1) VS Code 상단 메뉴에서 파일(File) → 폴더 열기(Open Folder)를 선택합니다.

(2) 원하는 위치에 새 폴더를 하나 만듭니다(예: "google-gws").

(3) 그 폴더를 선택해서 엽니다. 이제 VS Code에 세 영역이 보입니다. 왼쪽은 파일 영역, 가운데는 작업 영역, 오른쪽은 AI 패널입니다.

제3부 GWS CLI 설치하기

두 가지 경로가 있습니다. 자동 설정(gws auth setup)과 수동 설정입니다.

경로 A — gws auth setup으로 자동 설정 (권장)

이 방법은 gcloud CLI가 먼저 설치되어 있어야 합니다.

가. gcloud CLI 설치

(1) https://cloud.google.com/sdk/docs/install 에 접속합니다.

(2) 운영체제에 맞는 설치 파일을 다운로드합니다.

(3) 설치 프로그램의 안내에 따라 설치를 완료합니다.

(4) 터미널에서 gcloud --version을 입력해 설치를 확인합니다.

나. GWS CLI 설치

(1) 터미널을 열고 아래 명령어를 입력합니다.

(2) 설치가 끝나면 gws --version으로 확인합니다. npm 패키지는 운영체제에 맞는 네이티브 바이너리를 자동으로 포함하므로 별도의 빌드 도구가 필요 없습니다.

다. 자동 설정 실행

(1) 터미널에서 아래 명령어를 입력합니다.

(2) 5단계 위자드가 시작됩니다. Step 1에서 gcloud CLI를 확인하고, Step 2에서 구글 계정 인증을 하고, Step 3에서 GCP 프로젝트를 선택하거나 새로 만들고, Step 4에서 활성화할 워크스페이스 API를 선택하고, Step 5에서 OAuth 자격 증명을 생성합니다.

(3) 체크마크는 스페이스바로 선택하고, 다음 단계로 넘어갈 때는 엔터키를 누릅니다.

(4) API 선택 화면에서는 Gmail, Google Drive, Google Calendar, Google Docs, Google Sheets, Google Slides를 선택합니다.

(5) 모든 단계가 끝나면 브라우저가 열리고 구글 계정 로그인을 요청합니다. 로그인하면 인증이 완료됩니다.

경로 B — 수동 설정 (gcloud가 없는 경우)

가. GWS CLI 설치 (경로 A와 동일)

나. 구글 클라우드 콘솔에서 프로젝트 만들기

(1) 브라우저에서 https://console.cloud.google.com 에 접속합니다.

(2) 구글 계정으로 로그인합니다.

(3) 화면 상단의 프로젝트 선택 드롭다운을 클릭합니다.

(4) "새 프로젝트"를 클릭합니다.

(5) 프로젝트 이름에 "gws-cli"라고 입력합니다.

(6) "만들기"를 클릭합니다.

다. API 활성화하기

(1) 왼쪽 메뉴에서 "API 및 서비스" → "라이브러리"를 클릭합니다.

(2) 검색창에 "Gmail API"를 입력하고 클릭한 뒤 "사용" 버튼을 누릅니다.

(3) 같은 방법으로 다음 API들을 활성화합니다: Google Drive API, Google Calendar API, Google Docs API, Google Sheets API, Google Slides API

라. OAuth 동의 화면 설정

(1) 왼쪽 메뉴에서 "API 및 서비스" → "OAuth 동의 화면"을 클릭합니다.

(2) "시작하기" 또는 "동의 화면 구성"을 클릭합니다.

(3) 앱 이름에 "gws-cli"를 입력합니다.

(4) 사용자 지원 이메일에 본인 이메일을 넣습니다.

(5) 사용자 유형은 "외부(External)"를 선택합니다.

(6) 개발자 연락처 이메일에도 본인 이메일을 넣습니다.

(7) "만들기" 또는 "저장 후 계속"을 클릭합니다.

(8) 중요: "대상" 탭에서 "앱 게시" 버튼을 반드시 눌러야 합니다. 누르지 않으면 토큰이 7일마다 만료됩니다.

마. OAuth 클라이언트 ID 만들기

(1) 왼쪽 메뉴에서 "API 및 서비스" → "사용자 인증 정보"를 클릭합니다.

(2) 상단의 "+ 사용자 인증 정보 만들기" → "OAuth 클라이언트 ID"를 클릭합니다.

(3) 애플리케이션 유형은 반드시 "데스크톱 앱(Desktop app)"을 선택합니다. GWS가 localhost 리다이렉트를 사용하기 때문입니다.

(4) 이름에 "gws-cli"를 입력합니다.

(5) "만들기"를 클릭합니다.

(6) 클라이언트 ID와 클라이언트 시크릿이 표시됩니다. 메모장에 복사해 둡니다.

(7) "JSON 다운로드" 버튼을 클릭해서 JSON 파일을 저장합니다.

바. JSON 파일을 GWS 설정 폴더에 옮기기

맥의 경우 터미널에서 아래 명령어를 순서대로 입력합니다.

윈도우의 경우 다운로드 폴더에 있는 client_secret으로 시작하는 JSON 파일을 %USERPROFILE%\.config\gws\ 폴더로 옮기면 됩니다.

사. 로그인하기

(1) 터미널에서 아래 명령어를 입력합니다.

(2) 브라우저가 열리면 구글 계정으로 로그인합니다.

(3) "Google에서 이 앱을 확인하지 않았습니다"라는 경고가 나올 수 있습니다. "계속(Continue)"을 클릭합니다.

(4) 권한 체크박스가 나타나면 필요한 범위를 선택하거나 "모두 선택(Select all)"을 클릭합니다.

(5) "You may now close this window"라는 메시지가 나오면 인증 완료입니다.

설치 확인

터미널에서 아래 명령어를 입력해 봅니다.

인증 상태가 표시되면 성공입니다. 실제 API 작동도 테스트합니다.

구글 드라이브의 파일 5개가 JSON 형태로 출력되면 모든 설정이 완료된 겁니다.

제4부 클로드 코드와 GWS CLI 연결하기

GWS CLI를 클로드 코드와 함께 쓸 때 MCP 서버를 별도로 설정할 필요가 없습니다. 클로드 코드는 GWS CLI를 일반적인 터미널 도구로 사용합니다. 두 가지 방식이 있습니다.

방식 A — 에이전트 스킬 설치 (권장)

GWS 저장소는 클로드 코드를 위해 설계된 92개의 공식 스킬을 제공합니다. 터미널에서 아래 명령어를 입력합니다.

설치된 각 스킬은 대응하는 gws 헬퍼 명령어를 사용하도록 클로드 코드에게 가르칩니다. 여러 단계의 작업을 자동으로 처리하는 단일 호출 단축키입니다.

설치 후 사용 가능한 주요 명령어:

방식 B — MCP 서버로 연결

GWS CLI를 MCP 서버로 띄워서 클로드 데스크톱이나 VS Code에서 도구로 쓸 수도 있습니다.

클로드 코드(터미널 버전)에서 MCP를 등록하려면:

제5부 VS Code 바이패스 퍼미션 모드 설정

클로드 코드가 매번 "이 작업을 허가하시겠습니까?"라고 물어보는 것이 번거로울 수 있습니다. AI에게 전적으로 맡기고 싶다면 바이패스 퍼미션 모드를 활성화합니다.

(1) AI 패널 상단에서 Shift+Tab을 누르면 모드가 전환됩니다.

(2) 바이패스 퍼미션 모드가 보이지 않으면 VS Code 설정(⚙)에 들어갑니다.

(3) 검색창에 "bypass"를 입력합니다.

(4) "Claude Code: Allow Dangerously Risky Permission" 체크박스를 활성화합니다.

(5) 이제 클로드 코드가 허가를 구하지 않고 바로 실행합니다.

주의: 이 모드에서는 AI가 파일 삭제나 시스템 변경도 묻지 않고 실행할 수 있으므로, 중요한 작업 전에는 백업을 권장합니다.

제6부 실전 활용 — 이메일 249개 자동 분류

AI 패널에 아래와 같이 입력합니다.

"이메일 최근 30일 동안 온 것들을 중요도 순으로 점수 매겨 줘. 중요하지 않은 건 읽음 처리하고, 중요도 높은 건 나한테 보고해 줘. 뉴스레터는 요약 정리해서 구글 독스에 저장해 줘. GWS 활용해서 진행해 줘."

클로드 코드는 이 명령을 받아서 gws gmail 관련 명령어를 조합해 실행합니다. 실행 결과로 249개의 이메일이 중요도별로 분류되고, 강의 제안은 즉시 확인 항목으로, 뉴스레터 189개는 요약 정리되어 구글 독스에 저장됩니다. 클로드 코드가 GWS를 인식하지 못하는 듯하면 "GWS CLI가 설치되어 있고 인증 완료되어 있어"라고 한 번 더 알려 주면 됩니다.

제7부 실전 활용 — 유튜브 → 구글 독스 가이드 생성

AI 패널에 아래와 같이 입력합니다.

"이 유튜브 링크(URL 붙여넣기)의 영상 내용을 가이드 형태로 구글 독스에 정리해서 저장해 줘."

클로드 코드는 유튜브 자막을 추출하고, 핵심 내용을 정리한 뒤, 구글 독스 API를 통해 볼드체, 구분선, 이모티콘까지 포함된 서식이 갖춰진 문서를 만들어 줍니다. 서식을 더 예쁘게 하고 싶다면 "구글 독스 서식이나 볼드체 다르게 하는 스킬 있지 않아?"라고 물어보면 됩니다.

제8부 실전 활용 — 구글 슬라이드 자동 생성

(1) VS Code 왼쪽 파일 영역에 "brand"라는 폴더를 만들고, 그 안에 브랜드 로고와 가이드라인 파일을 넣습니다.

(2) AI 패널에 입력합니다.

"이 유튜브 내용에 대한 슬라이드를 brand 폴더에 있는 로고와 가이드라인 참고해서 구글 슬라이드로 만들어 줘."

클로드 코드에는 눈이 없습니다. 코드로 슬라이드를 만들기 때문에 레이아웃이 완벽하지 않을 수 있습니다. 이때 "GWS의 스크린샷 찍어서 레이아웃 고쳐 주는 스킬 있지 않아?"라고 물어보면, get thumbnail 스킬로 각 슬라이드를 캡처한 뒤 레이아웃 문제를 스스로 발견하고 수정합니다. 마지막 페이지의 로고가 잘렸다면 "마지막 페이지 로고가 잘렸어, 수정해 줘"라고 구체적으로 지시하면 됩니다.

제9부 오류가 발생했을 때 대처법

1. 브라우저가 안 열릴 때

gws auth login을 실행했는데 브라우저가 자동으로 열리지 않으면, 터미널에 출력된 URL을 복사해서 브라우저에 직접 붙여넣습니다.

2. "client_secret.json not found" 오류

GWS가 client_secret.json을 찾을 수 없다는 뜻입니다. 아래 명령어로 확인합니다.

결과가 null이면 구글 클라우드 콘솔에서 파일을 다시 다운로드해야 합니다.

3. 토큰이 7일 만에 만료될 때

외부 사용자 유형으로 구성되고 게시 상태가 "테스트"인 프로젝트에는 7일 후 만료되는 갱신 토큰이 발급됩니다. OAuth 동의 화면의 "대상" 탭에서 앱을 "게시(Published)" 상태로 전환하면 해결됩니다.

4. 화면 캡처로 오류 해결하기

VS Code의 AI 패널에 이미지를 드래그앤드롭하거나 골뱅이(@)를 입력해서 이미지 파일을 참조할 수 있습니다. 오류 화면을 캡처해서 "이 오류 처리해 줘"라고 하면 클로드 코드가 분석해서 해결 방법을 제시합니다. 말로 설명해 보고, 안 되면 이미지로 보여 주는 방식이 가장 확실합니다.

제10부 활용 아이디어 모음

•매일 아침 자동 브리핑 — "오늘 할 일 말해 줘"라고 하면 지난 24시간의 이메일을 분석하고, 캘린더 일정을 확인하고, 중요한 내용을 요약합니다.

•뉴스레터 자동 정리 — 구독 중인 뉴스레터를 자동으로 분류하고, 구글 독스에 주간 요약 문서를 생성합니다.

•스프레드시트 → 문서 변환 — 구글 시트에 있는 데이터를 구글 독스 보고서로 추출합니다.

•캘린더 빈 시간대 자동 스케줄링 — 구글 캘린더의 빈 시간을 확인해서 미팅을 자동으로 잡습니다.

•콘텐츠 파이프라인 자동화 — 구글 독스에서 새 글 초안을 감지하고, 내용을 가져와서 처리 파이프라인을 통해 CMS에 푸시합니다.

•미팅 사전 준비 에이전트 — 오늘의 캘린더 일정을 가져오고, 관련 이메일과 교차 참조하여 브리핑 문서를 자동 생성합니다.

제11부 주요 GWS CLI 명령어 정리

제12부 핵심 정리

GWS CLI는 구글 워크스페이스 전체를 터미널 명령어 한 줄로 조종하는 만능 리모콘입니다. 설치 과정을 요약하면 이렇습니다.

자동화는 도구가 먼저가 아닙니다. 내 업무 중에서 반복되는 작업이 무엇인지 파악하고, 그것을 AI에게 어떻게 맡길지 설계하는 것이 먼저입니다. GWS CLI는 그 설계를 실행에 옮기는 통로입니다.