구글 워크스페이스 CLI란 무엇인가 — 핵심 3줄 요약

구글 워크스페이스 CLI(gws)는 Gmail, 드라이브, 캘린더, 시트, 독스, 챗 등
구글 워크스페이스 전 서비스를 터미널 명령어로 제어할 수 있는 통합 CLI 도구입니다.
2026년 3월 초, 구글 워크스페이스 팀 내부자가 오픈소스로 공개했으며,
공식 GitHub 저장소 googleworkspace/cli에서 누구나 무료로 사용할 수 있습니다.

이 도구의 공식 슬로건은 “One CLI for all of Google Workspace — built for humans and AI agents”입니다.
사람도 쓸 수 있지만, 설계 철학의 중심은 AI 에이전트입니다.
AI 에이전트는 마우스 클릭보다 텍스트 명령어를 훨씬 정확하게 처리하기 때문에,
CLI는 에이전트가 워크스페이스 생태계를 장악하기 위한 가장 효율적인 무기가 됩니다.

기술 스택도 중요합니다. Go 언어로 작성돼 실행 속도가 빠르고,
npm 패키지 형태로 배포되어 Node.js 환경만 있으면 모든 OS에서 즉시 설치됩니다.
모든 API 응답은 JSON 형식으로 출력돼 스크립트 파이프라인에 바로 투입할 수 있고,
구글의 디스커버리 서비스(Discovery Service)를 런타임에 읽어 명령어를 동적으로 생성하기 때문에
구글이 새 API를 추가하면 gws도 자동으로 최신 상태를 유지합니다.

▲ 목차로 돌아가기

MCP 방식과 뭐가 다른가 — 진짜 차이점 비교

gws CLI의 가치를 제대로 이해하려면 지금까지 많이 쓰이던 MCP(Model Context Protocol) 방식과 비교해야 합니다.
MCP는 Anthropic이 2024년 11월 공개한 오픈 표준으로, AI 모델과 외부 서비스를 연결하는 중간 다리 역할을 합니다.
Claude 데스크톱이나 VS Code에서 Gmail, 드라이브 등을 MCP 서버로 연결해 사용하는 것이 대표적인 방식이었습니다.

문제는 MCP 방식에 구조적 한계가 있다는 점입니다. 보안상의 이유로 기능 범위가 제한되는 경우가 잦아서,
Gmail MCP 서버로 메일 초안을 작성하는 것은 가능하지만 실제 전송은 사람이 수동으로 해야 하는 상황이 반복됩니다.
또 MCP 클라이언트는 보통 도구(tool)를 50~100개까지만 등록할 수 있는데,
워크스페이스 서비스 하나당 10~80개의 도구가 필요하니 금방 한계에 부딪힙니다.

중요한 것은, gws CLI가 MCP를 대체하는 게 아니라 보완하고 확장한다는 점입니다.
gws CLI 자체가 MCP 서버 모드(gws mcp)를 지원하기 때문에,
Claude 데스크톱이나 Gemini CLI 같은 MCP 호환 앱에서도 gws를 연결해 사용할 수 있습니다.
즉, MCP 생태계 위에서 gws가 더 강력한 실행 레이어로 작동하는 구조입니다.
“제안하는 AI”에서 “실행하는 에이전트”로의 전환이 바로 이 지점에서 일어납니다.

▲ 목차로 돌아가기

설치부터 인증까지 — 삽질 없는 세팅 가이드

gws CLI의 가장 큰 장점 중 하나는 설치가 극도로 간단하다는 점입니다.
Rust와 Go로 작성됐지만 빌드 환경은 전혀 필요 없고,
Node.js 18 이상이 설치된 환경이라면 터미널에 한 줄이면 끝납니다.

# 설치
sudo npm install -g @googleworkspace/cli
# 설치 확인
gws --version
gws help

설치보다 까다로운 것이 인증 단계입니다. 크게 두 가지 경로가 있습니다.
gcloud CLI가 이미 설치돼 있다면, gws auth setup 명령어 하나로
GCP 프로젝트 생성, API 활성화, OAuth 로그인까지 자동으로 완료됩니다.
gcloud가 없다면 수동 세팅이 필요합니다.

인증이 완료되면 자격 증명은 AES-256-GCM으로 암호화돼 OS 키링에 안전하게 저장됩니다.
신규 GCP 계정이라면 90일 동안 약 40만 원 상당의 무료 크레딧이 제공되며, 체험 기간 후 자동 유료 전환은 없습니다.
CLI 자체는 완전 무료 오픈소스이므로 추가 과금 부담 없이 충분히 테스트해볼 수 있습니다.

▲ 목차로 돌아가기

Gmail·Drive·Sheets·Calendar 실전 자동화

세팅을 마쳤다면 이제 진짜 핵심입니다. gws CLI가 지원하는 서비스별 자동화 가능성을 실전 관점에서 살펴봅니다.
아래 예시들은 에이전트에게 스킬로 등록했을 때 자연어 요청 한 줄로 처리되는 시나리오들입니다.

Gmail 자동화: 메일 읽고, 분석하고, 전송까지

MCP 방식과 가장 극명하게 차이 나는 영역이 Gmail입니다.
gws gmail users messages send 명령어를 에이전트 스킬로 등록하면,
“어제 받은 계약 관련 메일에 긍정적인 답장을 보내줘”라는 요청 하나로
이전 대화 맥락 파악 → 답장 초안 작성 → 실제 전송까지 자동 처리됩니다.
메일 스레드 검색, 라벨 관리, 휴가 자동 응답 설정도 CLI 명령어로 가능합니다.

# 최근 메일 목록 JSON으로 조회
gws gmail users messages list --user-id me --output json
# 특정 조건으로 메일 검색
gws gmail users messages list --user-id me \
--q "from:partner@company.com is:unread"

Drive 자동화: 폴더 구조 설계부터 대량 이동까지

드라이브 자동화는 대량 파일 작업에서 진가가 드러납니다.
“업무 파일을 프로젝트별로 정리해줘”라고 요청하면 에이전트가 폴더 구조를 설계하고,
파일을 검색해서 분류하고, 권한 설정까지 완료합니다.
GUI에서 폴더 하나씩 만들고 이름 바꾸던 작업을 수십 초 안에 처리하는 경험은 꽤 충격적입니다.
공유 드라이브 관리, PDF/DOCX 내보내기, 코멘트 조회도 지원합니다.

Sheets 자동화: 서식·데이터·스타일까지 한 번에

구글 시트 자동화는 단순 데이터 입력을 훨씬 넘어섭니다.
헤더 행 고정(Freeze), 셀 서식 지정, 행·열 삽입, 주석·링크 관리, 스타일링까지 CLI로 제어됩니다.
단, 스프레드시트 범위 지정 시 느낌표(!)가 들어가는 표현은 bash의 히스토리 확장 문자로 해석될 수 있으니,
반드시 작은따옴표로 감싸는 것을 잊지 마세요.

# 시트 데이터 JSON으로 추출 (작은따옴표 필수)
gws sheets spreadsheets.values get \
--spreadsheet-id "YOUR_SHEET_ID" \
--range 'Sheet1!A1:D10' \
--output json | jq '.values'

Calendar 자동화: free/busy 확인부터 팀 일정까지

캘린더에서 가장 유용한 기능은 free/busy 상태 확인입니다.
팀원들의 가용 시간대를 자동으로 스캔해서 최적의 회의 시간을 잡는 시나리오가 가능해집니다.
focus-time(집중 시간), out-of-office(부재 중), working-location(근무 위치) 같은
특수 이벤트 유형도 지원돼서 복잡한 일정 관리를 에이전트에게 완전히 위임할 수 있습니다.

▲ 목차로 돌아가기

Claude·Gemini와 연동하는 스킬 확장법

gws CLI를 설치했다고 해서 자동으로 에이전트가 이를 활용하지는 않습니다.
에이전트가 이 CLI를 “언제, 어떻게 써야 하는지” 알려주는 스킬(SKILL.md)을
등록해야 비로소 자연어 요청이 CLI 명령어 시퀀스로 변환됩니다.

전체 스킬 한 번에 설치하기

# 전체 스킬 일괄 설치
npx skills add https://github.com/googleworkspace/cli
# Gmail 스킬만 선택 설치
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
# Gemini CLI 확장으로 설치
Claude 데스크톱에 MCP 서버로 연결하기

Claude 데스크톱을 사용 중이라면 MCP 설정 파일에 아래 내용을 추가하면 됩니다.
설정 후 Claude에게 "오늘 받은 메일 중 중요한 것 요약해줘" 같은 요청을 자연어로 하면
gws가 실제 Gmail API를 호출해 결과를 가져옵니다.

{
"mcpServers": {
"gws": {
"command": "gws",
"args": ["mcp"]
}
}
}

💡

스킬 등록 핵심 팁: 스킬을 무조건 많이 넣는 것보다 실제로 쓸 서비스만 골라 등록하는 게 중요합니다.

서비스 하나당 도구가 10~80개씩 추가되어 MCP 클라이언트의 도구 제한(50~100개)에 걸릴 수 있습니다.

Drive, Gmail, Sheets 3개만 먼저 등록하고 필요에 따라 확장하는 전략을 권장합니다.

현재 스킬 실행 정확도는 테스트 결과 50~70% 수준이므로, 중요한 작업은 결과를 반드시 확인하세요.


터미널에서 한 번 인증만 하면 Gemini 에이전트가 gws 명령어를 직접 실행합니다.

Codex나 Claude Code 같은 코딩 에이전트에 스킬을 등록하면,

"지난주 회의록 찾아서 요약하고 팀 채팅방에 공유해줘"처럼 복합적인 워크플로우도 자동으로 분해·실행됩니다.

▲ 목차로 돌아가기