gws（Google Workspace CLI）のセットアップ手順 — Claude Code から自分のスプレッドシート・Gmail・カレンダーを叩く

TL;DR

gws は Google が公開している Workspace 用 CLI（googleworkspace/cli）。「公式」とリポジトリにあるが、ヘルプには This is not an officially supported Google product と明記されている（公式リポジトリで配布されているが公式サポートは付かない）
一度設定すれば、ターミナルから自分のスプレッドシート・Gmail・カレンダー・Drive・Docs・Chat・Tasks 等を JSON で叩ける
Claude Code や Codex に「先月の経費スプレッドシートを読んでまとめて」「カレンダーの来週の予定をテーブルで」と日本語で頼むだけで、これらを叩いて結果を返してくれるようになる
設定で詰まるのは GCP プロジェクト側の OAuth クライアント作成 の一箇所だけ。そこを画像なしの手順で通す

何ができるか（最初の絵）

セットアップ後、こういうコマンドが Claude Code やシェルから直接通る。

# スプレッドシート読み取り
gws sheets +read --spreadsheet <SHEET_ID> --range 'Sheet1!A1:Z100'

# 今日のカレンダー予定
gws calendar +agenda --today --format table

# 直近7日の未読メール
gws gmail users messages list --params '{"userId": "me", "q": "newer_than:7d is:unread", "maxResults": 10}'

# Drive にローカルファイルをアップロード
gws drive +upload ./report.pdf --parent <FOLDER_ID>

# Chat スペースに投稿
gws chat +send --space spaces/AAAAxxxx --text '日次レポート上がりました'

これを Claude Code のセッション内で gws ... と直接実行できるので、「スプレッドシートを読んでサマライズして」「先方にメールの下書きを作って」のような依頼が一段で通る。

前提と必要なもの

必要なもの	用途
Google アカウント（個人 or Workspace）	OAuth でログインするアカウント
GCP（Google Cloud Platform）プロジェクト	OAuth クライアント発行の入れ物。請求先カードの登録は不要（無料枠で完結）
`gcloud` CLI	GCP プロジェクト操作とAPI有効化に使う
Node.js + pnpm（または npm）	gws 本体のインストール
ブラウザ	OAuth 同意画面の操作と認証で開く

gws は非公式扱いなので、Google 公式の OAuth クライアント ID が同梱されていない。利用者が自分の GCP プロジェクトで Desktop app クライアントを作り、その ID とシークレットを gws に渡す必要がある。ここが詰まりやすい唯一の箇所で、本記事はここに紙幅を割く。

Step 1: `gws` 本体をインストールする

pnpm か npm でグローバルインストールする（どちらでもよい）。

# pnpm の場合（筆者環境）
pnpm add -g @googleworkspace/cli

# npm の場合
npm install -g @googleworkspace/cli

確認:

gws --version
# gws 0.18.x
# This is not an officially supported Google product.

インストール先（Windows + pnpm 例）:

C:\Users\<USER>\AppData\Local\pnpm\gws

設定ディレクトリ（OS共通の論理パス）:

~/.config/gws/（Windows では C:\Users\<USER>\.config\gws\）

Step 2: `gcloud` CLI を入れて GCP プロジェクトを準備

gws auth setup は内部で gcloud を呼ぶので、先に gcloud CLI を入れて自分の Google アカウントでログインしておく。

# gcloud CLI のインストールは公式手順に従う
# https://cloud.google.com/sdk/docs/install

# 認証（ブラウザが開く）
gcloud auth login

# プロジェクト作成（任意の名前。例: gws-personal-2026）
gcloud projects create gws-personal-2026 --name "gws CLI personal"

# 作ったプロジェクトを active にする
gcloud config set project gws-personal-2026

既存プロジェクトを使う場合は gcloud config set project <既存プロジェクトID> だけで OK。

Step 3: `gws auth setup` でAPI有効化を一括で済ませる

gws auth setup

このコマンドは内部で次を行う。

gcloud の存在と認証を確認
アクティブな GCP プロジェクトを確認
Workspace 系のAPI（Drive, Sheets, Gmail, Calendar, Chat, Docs, Slides, Tasks 等）をプロジェクトに対して一括有効化
OAuth クライアント作成を試みる → ここで止まる（手作業が必要）

途中で次のようなメッセージが出る。

OAuth client creation requires manual setup in the Google Cloud Console.

これは想定挙動で、ここから先は Cloud Console の Web UI で 2 つの設定 をする必要がある。出力されたURLをそのまま開いてもいい。

ブラウザで次を開く（プロジェクト ID を自分のものに置換）。

https://console.cloud.google.com/apis/credentials/consent?project=<YOUR_PROJECT_ID>

設定内容:

項目	値
User Type	External
App name	`gws CLI`（または好きな名前）
User support email	自分の Google アカウントメール
Developer contact information	自分のメール
Scopes	この画面では追加しない（後で gws が要求する）
Test users	自分の Google アカウントを必ず追加（External + テスト中は test user 以外ログインできない）

「Save and continue」で最後まで進めて保存。

注意点:

External で公開（Publish App）する必要はない。 Testing 状態のまま で使う
Testing 状態のままだと、OAuth トークンは 7日で期限切れになる仕様。期限が切れたら gws auth login で再認証すれば良い（実用上はそこまで頻繁ではない）
個人で使う限りこれで十分。組織で配布したい場合は別途「Workspace ドメイン内 Internal」設定や検証申請が必要

Step 5: OAuth クライアント ID（Desktop app）を作る

ブラウザで次を開く。

https://console.cloud.google.com/apis/credentials?project=<YOUR_PROJECT_ID>

手順:

上部「+ CREATE CREDENTIALS」→「OAuth client ID」を選ぶ
Application type: Desktop app を選ぶ
Name: gws CLI（任意）
「CREATE」を押す
ダイアログに Client ID と Client Secret が表示される
ダイアログ下部の「DOWNLOAD JSON」で JSON ファイルをダウンロードする

ダウンロードした JSON は client_secret_<長い文字列>.apps.googleusercontent.com.json という名前で落ちてくる。

Step 6: client_secret.json を gws に渡す

3つの方法のうち、お好みで。筆者は方法B（JSON ファイル配置）が一番後でハマらず楽だった。

方法 A: 環境変数（CI やスクリプト向き）

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="<your-client-id>"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="<your-client-secret>"
gws auth login

方法 B: JSON ファイルを所定の場所に置く（推奨）

ダウンロードした JSON を以下のパスにリネームして配置する。

Linux/macOS: ~/.config/gws/client_secret.json
Windows: C:\Users\<USER>\.config\gws\client_secret.json

ディレクトリが無ければ mkdir -p ~/.config/gws で作る。

# Windows (Git Bash)
mkdir -p "$HOME/.config/gws"
mv "$HOME/Downloads/client_secret_*.json" "$HOME/.config/gws/client_secret.json"

gws auth login

方法 C: `gws auth setup` をもう一度走らせる（対話モード）

gws auth setup --login

対話で client_secret の中身を聞かれるので貼り付ける。

gws auth login

ブラウザが開く → 自分の Google アカウントを選ぶ → 「このアプリは Google で確認されていません」と警告が出る → 「詳細」→「安全でないページに移動（〇〇にアクセスする）」 → スコープを確認して「続行」。

警告が出るのは Step 4 で External（Testing 状態）にしたから。Test users に自分を入れてあれば進める。

完了するとターミナルに Authentication successful のような表示が出て、トークンがキャッシュされる。

Step 8: 動作確認

# 認証状態の確認
gws auth status

# 自分のプロフィール
gws people people get --params '{"resourceName": "people/me", "personFields": "names,emailAddresses"}'

# Drive のファイル5件
gws drive files list --params '{"pageSize": 5}' --format table

# カレンダー今日の予定
gws calendar +agenda --today --format table

ここまで通ればセットアップ完了。

必要なスコープ（読み取り専用で始めたいとき）

書き込みが怖いうちは読み取り専用で始める。

# 読み取り専用スコープでログイン
gws auth login --readonly

# サービスを限定（例: drive, sheets, gmail）
gws auth login -s drive,sheets,gmail

# 全スコープ（pubsub + cloud-platform 含む。未検証アプリだと restricted_client エラーになることがある）
gws auth login --full

実運用に入ったら、必要に応じて再度 gws auth login で書き込みスコープも追加する。

トラブルシューティング

`gcloud CLI not found`

gcloud が PATH に入っていない。Google Cloud SDK を再インストールし、PATH を通す。

`OAuth client creation requires manual setup`

Step 4 と Step 5 を実施する。これは想定挙動で、gws auth setup だけでは OAuth クライアントは作れない（Cloud Console の Web UI 操作が必須）。

「このアプリは Google で確認されていません」が出てログインできない

Step 4 の OAuth 同意画面で、自分のメールアドレスを Test users に追加し忘れている。Test users に追加して再度試す。

`Auth error (exit code 2)` が頻発する

トークンの期限切れ。OAuth 同意画面が Testing 状態だと7日で切れる。再認証する。

gws auth login

Windows で日本語が文字化けする

gws の出力は UTF-8 だが、Windows Git Bash の Python は stdin/stdout を cp932 でデコードするので化ける。Python にパイプするときは必ず PYTHONIOENCODING=utf-8 を付ける。

gws sheets +read --spreadsheet <ID> --range "シート名!A1:Z100" --format json 2>/dev/null \
  | PYTHONIOENCODING=utf-8 python3 -c "import json,sys; print(json.load(sys.stdin))"

スコープが足りないと怒られる

gws auth login でスコープを追加し直す。最初に --readonly でログインしている場合、書き込みは別途 gws auth login で全スコープ取り直す。

Claude Code から使うときの最低限のお作法

書き込み操作は実行前に確認: send, update, delete, create 系は、Claude Code に任せる前に「これでよい？」と聞く流れを残す
大量データは pageSize で制限: Drive や Gmail の list 系は最大数千件返ってくる。--params '{"pageSize": 20}' のように上限を切る
機密情報を含むメール本文は必要部分のみ表示: Gmail を Claude Code に読ませると、メール全文がコンテキストに乗る。CC/BCC や添付ファイルの取り扱いに注意
API 呼び出しの履歴は ~/.config/gws/cache/ に残る: ここに認証情報・キャッシュが置かれる。共用PCでは注意

次の一歩

Google Workspace CLI のスキーマを Claude Code に教える — gws schema <service.resource.method> で API スキーマを取れる
経費精算スプレッドシートの自動チェック、議事録 → Docs 起こし、カレンダー → 当日の準備物提示、など、社内の繰り返し業務をひとつだけ選んで gws + Claude Code 経由に乗せ替えてみる
不要になったスコープは gws auth logout で破棄してから再ログインで絞り直す

参考

リポジトリ: googleworkspace/cli
OAuth 同意画面の設定: Google Cloud ヘルプ — OAuth 同意画面の設定
Desktop アプリ用 OAuth クライアント: Google Identity — OAuth 2.0 for Mobile & Desktop Apps