Gmail, Drive, Calendar를 한 번에 묶자 — 에이전트 자동화용 CLI가 필요한 이유

처음엔 그냥 또 하나의 CLI인 줄 알았습니다. “Google API 래퍼겠지, 뭐” 하고 넘길 뻔했어요. 근데 설치하고 1시간 만에 제 AI 에이전트 시스템이 진짜로 바뀌어 있었습니다.

**gws(Google Workspace CLI)**는 2026년 3월 공개된 CLI 도구로, Drive·Gmail·Calendar·Sheets·Tasks 등 Google Workspace 전체를 하나의 명령줄에서 조작할 수 있게 해주는 오픈소스 프로젝트다. Google의 Discovery Service를 런타임에 읽어 명령 체계를 동적으로 구성하며, JSON 출력과 MCP 서버 모드를 내장해 AI 에이전트 연동에 특화됐다.

오늘 제가 실제로 한 일을 그대로 공유합니다. 이론이 아니라 경험입니다.

왜 AI 에이전트는 SaaS API 앞에서 자꾸 삐끗하는가

저는 Obsidian 볼트에 6,000개 넘는 노트를 관리하면서, Claude 에이전트 28개 스킬과 14개 에이전트를 돌리고 있습니다. 시스템 자체는 꽤 잘 돌아가요. 노트 정리, 블로그 작성, 트레이딩 분석까지 자동화했으니까요.

근데 Google 서비스와의 연결에서 항상 삐끗했습니다.

주간 점검 리마인더? 없어서 13일이나 빼먹음
KPI 추적표? 마크다운 테이블이라 폰에서 확인 불가
NotebookLM 동기화? “이번 주에 하겠다”고 적어놓고 한 번도 안 함
GOALS.md 업데이트? 24일째 방치 중

문제는 명확했어요. 에이전트가 Google 서비스를 직접 건드릴 방법이 없었습니다. Notion MCP는 있었지만, Google Calendar에 리마인더를 넣거나 Sheets에 데이터를 push하는 건 전부 수동이었거든요.

그래서 각 서비스마다 따로 API를 붙여야 하나 고민했는데, 그때 gws를 발견한 겁니다.

gws가 해결하려는 문제 정의

기존에 Google API를 쓰려면 이런 과정을 거쳤습니다:

1. 각 서비스별 API 문서 읽기 (Drive API, Calendar API, Sheets API...)
2. OAuth 인증 코드 작성
3. 서비스별 SDK 설치 + 래퍼 코드 작성
4. JSON 응답 파싱 로직 구현
5. 에러 핸들링, 페이지네이션 처리

서비스 3개만 붙여도 코드가 수백 줄이 됩니다. AI 에이전트한테 이걸 시키려면 더 복잡해지고요.

gws는 이걸 이렇게 바꿉니다:

# Calendar에 일정 추가
gws calendar events insert --params '{"calendarId":"primary"}' --json '{...}'

# Sheets에 데이터 push
gws sheets spreadsheets values append --params '{...}' --json '{...}'

# Drive에 파일 업로드
gws drive files create --json '{...}' --upload ./file.md

한 줄이면 됩니다. 별도 SDK 없이, 별도 코드 없이, Shell에서 바로 실행. AI 에이전트 입장에서는 Shell 도구 하나로 Google 전체를 조작할 수 있게 된 겁니다.

그리고 결정적으로 — MCP 서버 모드가 내장되어 있습니다.

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,sheets,calendar,tasks"]
    }
  }
}

이걸 Cursor의 .cursor/mcp.json에 넣으면, 에이전트가 Google 서비스를 직접 호출합니다. “Sheets에서 KPI 읽어줘”가 진짜로 되는 거예요.

실전: 1시간 만에 뭘 했나

이론은 여기까지. 제가 오늘 실제로 한 작업을 시간순으로 공유합니다.

10분: 설치 + 인증

npm install -g @googleworkspace/cli   # 6초 만에 설치 완료
gws --version                         # gws 0.6.0

GCP 프로젝트에서 OAuth 클라이언트 만들고, client_secret.json을 ~/.config/gws/에 넣고:

gws auth login -s drive,sheets,calendar,tasks

브라우저에서 Google 로그인 + 권한 허용. 끝. 이게 제일 오래 걸렸는데, 그래도 10분입니다.

5분: Calendar 리마인더 3개 등록

제가 가장 먼저 해결하고 싶었던 건 “주간 점검 까먹는 문제”였습니다.

gws calendar events insert --params '{"calendarId":"primary"}' --json '{
  "summary": "🧠 온톨로지 주간 점검",
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=SU"],
  "start": {"dateTime": "2026-03-08T20:00:00+09:00", "timeZone": "Asia/Seoul"},
  "reminders": {"useDefault": false, "overrides": [{"method": "popup", "minutes": 30}]}
}'

이 한 줄로 매주 일요일 20시에 알림이 옵니다. 같은 방식으로 “GOALS.md 월간 리뷰”(매월 1일), “Inbox PARA 정리”(매주 수요일)도 등록했습니다.

3개 리마인더에 걸린 시간: 5분. 13일 빼먹던 주간 점검이 이제 폰에서 알림으로 옵니다.

15분: Sheets 대시보드 생성

마크다운 테이블로 관리하던 KPI를 Google Sheets로 옮겼습니다.

gws sheets spreadsheets create --json '{
  "properties": {"title": "온톨로지 대시보드 2026"},
  "sheets": [
    {"properties": {"title": "KPI"}},
    {"properties": {"title": "Action Log"}},
    {"properties": {"title": "Content"}},
    {"properties": {"title": "Notes Index"}}
  ]
}'

4개 탭을 만들고, 헤더와 초기 데이터를 넣었습니다. 이제 폰에서 Google Sheets 앱을 열면 KPI가 바로 보입니다. 마크다운 파일을 열어서 테이블을 눈으로 파싱하던 시절은 끝났어요.

특히 “Notes Index” 탭이 핵심인데요 — inbox-organizer가 노트를 PARA 분류할 때마다 [날짜, 제목, 태그, 한줄요약, 경로]를 자동으로 push합니다. 나중에 “그 노트 뭐였지?” 할 때 Sheets 앱에서 검색하면 끝입니다.

20분: Drive 동기화 + NotebookLM 연결

“NotebookLM에 핵심 노트 올려야지” — 이 TODO를 2월부터 안 하고 있었거든요. 수동 업로드가 귀찮아서.

gws drive files create --json '{"name":"NotebookLM_Sync","mimeType":"application/vnd.google-apps.folder"}'

폴더 만들고, 핵심 노트 5개를 업로드했습니다:

파일	용도
GOALS.md	2026년 목표 전체
온톨로지-README.md	시스템 아키텍처
온톨로지-TODO.md	개선 과제 목록
주간점검 최신본	현재 상태 스냅샷
CLAUDE.md	AI 운영 가이드

이제 NotebookLM에서 이 Drive 폴더를 소스로 잡으면, “내 시스템 어떻게 돌아가?” 물어볼 때 맥락을 가진 대답이 나옵니다. 주간 셋업 때 gws drive files update로 변경된 파일만 덮어쓰면 동기화 끝.

10분: Google Tasks에 온톨로지 TODO 동기화

마크다운의 - [ ] 체크박스는 폰에서 쓰기 불편합니다. 특히 “Decisions DB 3/15까지 만들기” 같은 장기 과제는 까먹기 딱 좋죠.

gws tasks tasklists insert --json '{"title": "온톨로지 TODO"}'

gws tasks tasks insert --params '{"tasklist": "LIST_ID"}' --json '{
  "title": "GOALS.md 진행률 업데이트",
  "due": "2026-03-07T00:00:00Z"
}'

7개 항목을 넣었고, Google Calendar 앱에서 할 일로 바로 보입니다. 폰에서 체크하면 완료 처리되고, 주간 셋업 때 에이전트가 읽어서 마크다운에도 반영합니다.

구조화된 JSON 출력이 왜 중요한가

gws의 모든 응답은 JSON입니다. 이게 왜 중요하냐면 — AI 에이전트가 파싱 없이 바로 소비할 수 있어요.

{
  "id": "9ogq1l37uo4nq42f6t9c297ifc",
  "status": "confirmed",
  "summary": "🧠 온톨로지 주간 점검",
  "start": {"dateTime": "2026-03-08T20:00:00+09:00"}
}

에이전트가 이걸 받으면 별도 파싱 로직 없이 바로 판단할 수 있습니다. “다음 주간 점검이 일요일이네, 그전에 inbox 정리해야겠다” 같은 맥락 이해가 가능한 거예요.

이건 Google Discovery Service 기반 동적 명령 생성과 맞물려서 더 강력해집니다. Google이 새 API를 추가하면 gws가 자동으로 반영하거든요. 별도 업데이트 없이.

내가 느낀 점

솔직히 이 정도 연동을 1시간 만에 끝낼 줄 몰랐습니다.

예전에 Google Calendar API를 파이썬으로 붙여본 적이 있는데, OAuth 인증 코드만 작성하는 데 2시간이 걸렸거든요. 그때는 google-auth-oauthlib, google-api-python-client 설치하고, credential.json 읽고, flow 만들고, token 저장하고… 코드가 100줄이 넘었습니다.

gws는 이 전체를 gws auth login 한 줄로 해결합니다. 그리고 나서는 진짜 “하고 싶은 일”에만 집중할 수 있었어요.

제가 오늘 만든 건 결국 이겁니다:

Before: 에이전트 → Obsidian → (Google은 수동)
After:  에이전트 → Obsidian + Google (Calendar/Sheets/Drive/Tasks 직접 조작)

에이전트의 팔이 Google까지 닿게 된 거예요.

솔직한 마음

물론 걱정도 있습니다.

첫 번째, gws는 v0.6.0이고 “공식 Google 제품이 아닙니다(not an officially supported Google product)”라고 명시돼 있어요. v1.0 전에 breaking change가 올 수 있습니다. 그래서 저는 래퍼 스크립트를 통해 명령을 감싸고, credential 경로도 환경변수로 분리해뒀습니다.

두 번째, Google Sheets가 “또 다른 SoT(Single Source of Truth)”가 되면 안 됩니다. 제 원칙은 마크다운이 원본, Sheets는 뷰. 쓰기는 append only로만 하고, 수정은 마크다운에서 합니다.

세 번째, 커뮤니티 MCP 서버(taylorwilsdon의 google_workspace_mcp 등)도 있는데, gws는 MCP 서버 모드를 내장하고 있어서 별도 설치 없이 바로 쓸 수 있다는 게 차이점입니다. 다만 서비스당 10-80개 도구가 추가되니까, drive,sheets,calendar,tasks 정도로 제한하는 게 실용적이에요.

앞으로 할 것들

이번 주

NotebookLM에 Drive 폴더 연결 — 소스로 추가하고 “내 시스템 분석해줘” 테스트
일요일(3/8) 첫 주간 점검 리마인더 확인 — Calendar 알림이 제대로 오는지 체크
inbox-organizer 실행해서 Notes Index 탭 확인 — Sheets에 인덱스가 잘 쌓이는지 검증

이번 달

Google Forms로 Decision 로그 입력 폼 만들기 — 폰에서 의사결정을 구조화해서 기록
주간 셋업 에이전트에 Tasks 양방향 동기화 붙이기 — 완료된 Tasks를 마크다운에 자동 체크

의도적으로 안 하는 것

Gmail 자동화: 메일은 수동이 맞음. 자동화 리스크가 큼
Google Docs 동기화: 마크다운이 SoT. Docs 복제는 혼란만 가중
실시간 양방향 동기화: 충돌 관리가 폭발적으로 복잡해짐
전체 볼트 Drive 백업: iCloud 동기화로 충분

FAQ

Q: gws 설치에 뭐가 필요한가요? A: Node.js 18 이상이면 npm install -g @googleworkspace/cli 한 줄로 끝납니다. GCP 프로젝트와 OAuth 클라이언트 설정이 필요하지만, 10-15분이면 완료됩니다.

Q: 무료인가요? A: gws CLI 자체는 무료 오픈소스입니다. Google Workspace API 호출도 일반적인 사용 범위에서는 무료입니다(일일 쿼터 제한은 있음).

Q: 기존 Google MCP 서버가 있는데 gws를 써야 하나요? A: 커뮤니티 MCP 서버(Python 기반)도 훌륭하지만, gws는 MCP 서버 모드를 내장하고 있어 별도 설치 없이 gws mcp -s drive,sheets 한 줄로 MCP 서버가 됩니다. CLI + MCP를 동시에 쓸 수 있는 게 차이점입니다.

Q: v1.0 전이라 불안정하지 않나요? A: 제가 오늘 Calendar, Sheets, Drive, Tasks 4개 서비스를 써봤는데 에러 없이 작동했습니다. 다만 래퍼 스크립트로 감싸서 breaking change를 흡수할 수 있게 준비하는 걸 추천합니다.

Q: 어떤 서비스를 지원하나요? A: Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks, People, Chat, Forms, Keep, Meet 등 25개 이상. Google Discovery Service에서 동적으로 가져오기 때문에 새 API가 추가되면 자동 반영됩니다.

Q: MCP 서버 모드에서 도구가 너무 많아지지 않나요? A: 서비스당 10-80개 도구가 추가됩니다. Cursor의 도구 제한(보통 50-100개)을 고려해서 실제 쓰는 서비스 3-4개만 지정하세요. 저는 drive,sheets,calendar,tasks로 제한했습니다.

결론

“도구를 더 추가하지 말고, 있는 도구를 연결하라.”

이게 제가 지난 달 Obsidian CLI를 붙이면서 배운 교훈이었는데, 오늘 gws로 같은 경험을 했습니다. Obsidian 볼트는 원래 있었고, Google Calendar도 원래 있었고, AI 에이전트도 원래 있었습니다. gws라는 다리를 하나 놓았을 뿐인데, “에이전트가 Google을 못 건드린다”는 한계가 사라졌어요.

1시간 투자로 Calendar 리마인더, Sheets 대시보드, Drive 동기화, Tasks TODO 관리가 전부 에이전트 손에 들어갔습니다. 복잡한 코드 한 줄 안 쓰고요.

AI 에이전트를 운영하고 있다면, gws는 지금 당장 붙여볼 가치가 있습니다.

참고 자료

gws GitHub Repository — 공식 저장소, v0.6.0
gws npm 패키지 — 설치 페이지
Google Workspace Studio 발표 — Google의 에이전트 자동화 비전
CLIをAIエージェント向けに書き直す必要がある理由 — AI 에이전트용 CLI 설계 철학