① 구글 워크스페이스 CLI란? — 탄생 배경과 핵심 개념

구글 워크스페이스 CLI(gws)는 구글이 2026년 3월 초 깃허브 공식 조직 계정에 공개한
오픈소스 커맨드라인 도구입니다. 프로젝트 문서는 이 도구를 “인간과 AI 에이전트 모두를 위해 설계된
Google Workspace 전용 단일 CLI”라고 소개합니다. 즉, 사람이 터미널에서 직접 쓸 수도 있고,
AI 에이전트가 프로그래밍 방식으로 호출할 수도 있는 이중 목적의 인터페이스입니다.

탄생 배경에는 에이전틱 AI(Agentic AI)의 급부상이 있습니다. 2026년 초 오픈소스 AI 에이전트
플랫폼 OpenClaw가 등장하면서, AI가 사람 대신 이메일을 읽고 파일을 정리하고 일정을 잡는
‘행동하는 AI’ 시대가 열렸습니다. 그런데 기존 Google Workspace API는 에이전트가 사용하기에
지나치게 복잡했습니다. Gmail·Drive·Calendar가 각각 별도의 API와 인증 흐름, 응답 형식을
갖고 있어 연결하는 것 자체가 하나의 프로젝트 수준이었죠.

gws는 Gmail, Drive, Calendar, Docs, Sheets, Slides, Chat, Tasks, Classroom, Keep, Meet까지
Google Workspace의 거의 모든 서비스를 단일 바이너리 하나로 접근할 수 있게 합니다.
출시 직후 개발자 커뮤니티에서 폭발적인 반응을 얻어 빠르게 1만 4천 개 이상의 GitHub Star를
획득하며 주간 가장 빠르게 성장하는 개발 프로젝트 중 하나로 이름을 올렸습니다.

단, 중요한 사전 지식이 하나 있습니다. gws는 공식 구글 제품이 아닙니다.
깃허브 문서에도 명시돼 있습니다. 즉, 지원 SLA나 기업용 보안 보증이 제공되지 않는 ‘개발자 샘플’
수준의 오픈소스입니다. 이 점을 이해한 위에서 활용 전략을 세우는 것이 중요합니다.

▲ 목차로 돌아가기

② gws가 기존 방식과 다른 결정적 이유 3가지

Zapier나 n8n 같은 노코드 자동화 툴이 이미 있는데 왜 CLI가 필요한지 의문이 생길 수 있습니다.
gws가 가져오는 변화는 근본적으로 다릅니다. 기존 방식과의 차이를 세 가지 핵심으로 정리합니다.

차이 1: AI 에이전트 전용 설계 — 구조화된 JSON 출력

기존 GUI 기반 도구나 비공식 스크립트는 텍스트 형태의 비정형 응답을 반환합니다. AI 에이전트가
이런 응답을 파싱하려면 추가적인 프롬프트 엔지니어링이 필요하고, 응답 포맷이 바뀌면 에이전트 전체가
오동작할 수 있습니다. gws는 모든 출력을 구조화된 JSON으로 반환하도록 설계됐습니다. 에이전트가
--json 플래그 하나로
파싱 가능한 응답을 즉시 받을 수 있어, 프롬프트 낭비 없이 행동을 이어 갈 수 있습니다.

차이 2: 서드파티 없는 퍼스트파티 연결 — Zapier 유료 구독 불필요

Zapier와 n8n은 편리하지만 Google API를 중간에서 대행하는 구조이기 때문에 월정액 비용이 발생하고
데이터가 제3자 서버를 경유합니다. gws는 Google 공식 OAuth를 통해 로컬 머신이나 CI 서버에서
직접 API를 호출합니다. 외부 서비스 의존도가 없어 보안 측면에서도 우수하고, 개인 계정부터
Workspace 조직 계정까지 모두 지원합니다.

차이 3: MCP 내장으로 어떤 AI 에이전트와도 연결

gws는 Model Context Protocol(MCP) 서버 모드를 기본 내장하고 있습니다. Claude Desktop,
gws를 통해 Gmail과 Drive에 즉시 접근할 수 있습니다. 특정 AI 플랫폼에 종속되지 않는
범용 인터페이스인 셈입니다.

▲ 목차로 돌아가기

③ 설치부터 첫 명령어까지 — 5분 퀵스타트

gws 설치는 npm 또는 Homebrew(macOS) 두 가지 경로가 가장 간편합니다. 아래 단계를
순서대로 따라가면 5분 안에 Gmail 라벨 목록을 JSON으로 출력할 수 있습니다.

1. 1
   gws 설치 — npm 전역 설치가 가장 빠릅니다.
   macOS라면 brew install gogcli도 가능합니다.

1. 2
   Google Cloud Console에서 OAuth 클라이언트 생성 — Google Cloud Console에서
   프로젝트를 생성하고 사용할 API(Gmail, Drive, Calendar 등)를 활성화한 뒤,
   OAuth 2.0 클라이언트 ID(데스크톱 앱 유형)를 생성해 JSON 파일을 다운로드합니다.
2. 3
   자격증명 등록 및 계정 인증

1. 4
   첫 명령어 실행 — 환경 변수를 설정하고 Gmail 라벨을 조회해 보세요.

▲ 목차로 돌아가기

④ 100개 이상 에이전트 스킬 — 실전 활용 시나리오

gws가 단순 CLI 도구 이상인 이유는 100개 이상의 사전 제작 에이전트 스킬(Agent Skills)을
함께 제공하기 때문입니다. 이 스킬들은 AI 에이전트가 복잡한 프롬프트 엔지니어링 없이
Workspace 작업을 안정적으로 수행할 수 있도록 구조화된 도구 형태로 설계돼 있습니다.

대표 스킬과 레시피 목록

실전 시나리오: 회의록 자동화

아래는 AI 에이전트가 gws를 이용해 회의 후속 작업을 완전 자동화하는 전형적인 흐름입니다.
“오늘 회의 내용을 요약해서 참석자에게 이메일로 보내고, Drive 공유 폴더에 저장해줘”라는
단 한 문장의 지시로 에이전트가 다음을 순서대로 수행합니다.

이 4단계를 에이전트가 자율적으로 실행하면 사람은 최종 검토만 하면 됩니다. 필자의 관점에서
이 스킬 체계가 진짜 강력한 이유는 단순 명령 나열이 아니라, 각 스킬이 다음 스킬에 넘길
구조화된 컨텍스트를 자동으로 생성한다는 점입니다. 에이전트 체인이 끊기지 않고 이어지는
바로 그 연결 고리를 gws가 담당합니다.

▲ 목차로 돌아가기

⑤ MCP 서버로 쓰는 법 — Claude·Gemini 완전 연동

gws의 가장 파급력 있는 기능은 바로 MCP(Model Context Protocol) 서버 모드입니다.
gws를 MCP 서버로 실행하면 Claude Desktop, Gemini CLI, VS Code AI 확장, OpenClaw 등
MCP를 지원하는 모든 AI 에이전트 클라이언트가 Google Workspace를 네이티브 도구로 호출할 수 있습니다.

기술적으로는 gws가 stdio 위에서 MCP 엔드포인트를 노출하는 방식입니다. AI 에이전트는
별도의 커스텀 서버를 개발하지 않고도 gws에게 “최근 이메일 중 계약서 관련 첨부파일을 찾아서
Drive에 저장해줘”라고 요청하면, gws가 Gmail API와 Drive API를 순서대로 호출해 작업을 완료합니다.

Claude Desktop에 gws MCP 연결하기

위와 같이 설정하면 Claude Desktop에서 대화 중 “이번 주 일정 알려줘”라고 입력했을 때
Claude가 gws MCP를 통해 실시간으로 Google Calendar를 조회하고 결과를 바탕으로 답변합니다.
GOG_ENABLE_COMMANDS 환경변수로 에이전트가 접근할 수 있는 서비스를
gmail, calendar, drive 등으로 제한하는 것이 보안상 중요합니다.

▲ 목차로 돌아가기

⑥ 보안과 거버넌스 — 간과하면 계정 정지된다

gws는 강력한 만큼 잘못 사용하면 구글 계정이 자동으로 보호 조치(일시 정지)를 받을 수 있습니다.
이미 초기 사용자들 사이에서 무분별한 자동화 테스트 중 계정 플래그 사례가 보고됐습니다.
아래 보안 체크리스트를 반드시 점검하세요.

필수 보안 원칙 6가지

• 1
  최소 권한 원칙(Least Privilege): 실제로 필요한 서비스 스코프만
  인증 시 요청하세요. --services gmail,calendar --readonly처럼
  읽기 전용 스코프로 시작하는 것을 권장합니다.
• 2
  샌드박스 계정으로 먼저 테스트: 프로덕션 Workspace 계정이 아닌
  별도의 테스트 Gmail 계정으로 자동화를 먼저 검증하세요.
• 3
  인간 승인 게이트: 이메일 발송, 파일 삭제, 권한 변경처럼
  되돌리기 어려운 작업은 에이전트가 자동 실행하기 전에 인간 확인 단계를 거쳐야 합니다.
• 4
  프롬프트 인젝션 대비: 에이전트가 이메일이나 문서 내용을 읽고
  처리할 때, 그 내용 안에 악의적인 명령이 숨어 있을 수 있습니다. 신뢰할 수 없는 콘텐츠를
  에이전트가 직접 명령으로 실행하지 않도록 격리 처리가 필요합니다.
• 5
  토큰 관리: OAuth 리프레시 토큰을 환경변수나 코드에 하드코딩하지
  마세요. OS 키체인 또는 암호화된 파일 키링을 사용하고, 정기적으로 토큰을 재발급하세요.
• 6
  명령 허용 목록 설정: 에이전트가 실행할 수 있는 명령을
  GOG_ENABLE_COMMANDS
  환경변수로 명시적으로 제한하세요. 예를 들어 이메일 조회만 허용하고 발송은 차단하는 식입니다.

필자의 솔직한 견해를 말씀드리자면, gws는 개인 생산성 자동화 도구로는 지금 당장 써볼 만한
가치가 충분합니다. 반면 기업 환경에서는 ‘빠른 파일럿 → 보안 리뷰 → 제한적 프로덕션 도입’의
3단계 접근이 현실적입니다. “모든 것을 자동화하면 좋겠다”는 흥분보다 “어디까지 에이전트에게
맡길 것인가”라는 경계 설정이 더 중요한 질문입니다.

▲ 목차로 돌아가기