BackOps

Claude から Google Workspace を操作する：gws CLI セットアップ

gws (Google Workspace CLI) をインストールし、Claude から Drive・Sheets・Docs などを直接操作できるようにするまでの手順をまとめます。Mac / Windows 両対応。

ターミナル画面と Google Drive・Sheets・Docs のアイコンが繋がっている抽象イラスト

Claude から Google Drive のファイルを読んだり、スプレッドシートに書き込んだりできるようにする手順をまとめます。使うのは gws（Google Workspace CLI）というコマンドラインツールです。

gws とは

gws は Google Drive・Gmail・Calendar・Sheets・Docs・Chat・Admin など、Google Workspace のほぼ全 API を 1 つのコマンドで操作できる CLI です。googleworkspace GitHub Organization で開発されていますが、Google の公式サポート対象ではない点には注意してください。

導入すると次のようなことが Claude から自然言語で頼めるようになります。

  • 「Drive の 2026年4月_請求書 フォルダにあるファイル一覧を出して」
  • 「このスプレッドシートの A 列を集計して別シートに書き込んで」
  • 「議事録の要点を Doc にまとめて Drive に保存して」

Claude 単体でもファイルアップロードで Workspace ファイルを扱えますが、gws を入れると 既存の Drive 構造をそのまま操作 できるようになり、定型業務の自動化幅が一気に広がります。

全体像

セットアップは大きく 4 ステップです。

  1. gws をインストール
  2. Google Cloud プロジェクトを準備
  3. OAuth クライアントを作成して認証
  4. Claude から使えるように Skills を導入

所要時間は 30 分程度。途中、Google Cloud Console のブラウザ操作が入ります。

前提条件

  • macOS または Windows
  • Google アカウント（個人の @gmail.com でも可）
  • インターネット接続
  • ブラウザ（OAuth 認証で使用）

1. gws をインストール

macOS

Homebrew を使うのが簡単です。ターミナルで実行します。

brew install googleworkspace-cli

インストール後、バージョン確認:

gws --version

gws 0.x.x のように表示されれば OK です。

Windows

Windows は Homebrew が使えないため、GitHub Releases からバイナリを取得します。

  1. GitHub Releases ページ を開く
  2. 最新リリースの Assets から gws-windows-x86_64.zip（または aarch64）をダウンロード
  3. ZIP を展開して gws.exe を任意のフォルダに配置（例: C:\tools\gws\）
  4. そのフォルダを 環境変数 PATH に追加
    • 「設定」→「システム」→「バージョン情報」→「システムの詳細設定」→「環境変数」
    • Path を選んで「編集」→「新規」で C:\tools\gws を追加

PowerShell を再起動して確認:

gws --version

代替案: Node.js 18 以降が入っているなら npm install -g @googleworkspace/cli でも導入可能です。

gws --version でバージョンが表示されるターミナル画面

2. Google Cloud プロジェクトの準備

gws は Google Cloud プロジェクト経由で OAuth 認証を行います。新規プロジェクトを作成するのが分かりやすいので、その手順を書きます（既存プロジェクトを流用してもかまいません）。

gcloud CLI のインストール

macOS

brew install --cask google-cloud-sdk

Windows

  1. Google Cloud SDK インストールガイド (Windows) からインストーラーをダウンロード
  2. 実行して画面の指示に従う

gcloud にログインしてプロジェクト作成

gcloud auth login
gcloud projects create gws-workspace-XXXX --name="gws Workspace"
gcloud config set project gws-workspace-XXXX

XXXX は世界で一意になるよう、自分のイニシャルや年などで置き換えてください（例: gws-workspace-mzk2026）。

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

3. OAuth クライアントの作成

ここはブラウザでの手動操作が必要です。この章のテストユーザー登録を忘れると後続の認証で必ずエラーになる ので、最後まで丁寧に進めてください。

Google Cloud Console の Google Auth Platform で設定を進めます。以下の URL の <PROJECT_ID> を自分のプロジェクト ID に置き換えてアクセスしてください。

3-1. ブランディング設定

https://console.cloud.google.com/auth/branding?project=<PROJECT_ID>

「Get Started」をクリックして以下を入力:

項目値
App name任意（例: gws-cli）
User support email自分のメールアドレス
Audience（対象）External
Developer contact自分のメールアドレス

入力後「CREATE」で確定します。

Google Auth Platform のブランディング設定画面。Audience に External を選択している様子

3-2. テストユーザーの追加（最重要）

左メニューの「対象（Audience）」タブを開きます。

https://console.cloud.google.com/auth/audience?project=<PROJECT_ID>

「テストユーザー」セクションで + Add users をクリックし、自分の Google アカウント を入力して保存します。

対象（Audience）タブのテストユーザー追加画面。+ Add users から自分のメールアドレスを追加している様子

これを忘れると、認証時に「Google hasn’t verified this app / アクセスをブロックしました（403 access_denied）」というエラーが出て先に進めません。

3-3. OAuth クライアント ID の作成

左メニューの「クライアント（Clients）」タブを開きます。

https://console.cloud.google.com/auth/clients?project=<PROJECT_ID>

+ CREATE CLIENT をクリック。

項目値
Application typeDesktop app
Name任意（例: gws-cli-desktop）

「CREATE」で作成すると Client ID と Client secret が表示されます。次のステップで使うのでウィンドウは閉じずに開いたままにしてください。

OAuth クライアント作成完了ダイアログ。Client ID と Client secret が表示されている

4. gws にログイン

ターミナルで gws auth setup を実行します。

gws auth setup

対話プロンプトが出るので、画面の指示に従って先ほどコピーした Client ID と Client secret を貼り付けます。

セットアップが完了すると自動的に gws auth login が始まり、scope（権限）の選択画面に進みます。

scope の選び方

scope 選択画面が出たら、一番上の Recommended (Core Consumer Scopes) にカーソルを合わせてスペースキーで選択し、Enter で確定するのが一番簡単です。これだけで Drive・Gmail・Calendar・Docs・Sheets・Slides・Tasks の主要 API（合計 13 個程度の scope）に一括でアクセスできるようになります。

gws auth login の scope 選択画面。Recommended (Core Consumer Scopes) にチェックが入っている

注意: CLI の -s recommended フラグ（プリセット名）は 85 個以上の scope を含むため @gmail.com アカウント（テストモード上限 ~25 個）ではエラーになります。画面 UI の Recommended (Core Consumer Scopes) は別物で、こちらは安全に使えます。

Admin SDK や Vault など追加の scope が必要な場合は、Recommended に加えて個別にスペースで選択してください。

ブラウザでの同意

ブラウザが自動で開きます。

  1. 自分の Google アカウントを選択
  2. 「Google hasn’t verified this app」警告が出たら Advanced → Go to … (unsafe) で進む（自分で作ったクライアントなので問題ありません）
  3. scope のチェックボックスで Select all または個別選択して「Continue」

「You can close this window」と出れば完了です。

5. 動作確認

ターミナルで Drive のファイルを取得してみます。

gws drive files list --params '{"pageSize": 5}'

JSON でファイル一覧が返ってくれば成功です。

gws drive files list の実行結果。Drive のファイルが JSON で表示されている

6. Claude から使えるようにする

gws をインストールしただけでは、Claude は使い方を知りません。リポジトリに同梱されている Agent Skills を導入することで、Claude が自動的に gws のコマンドを正しく組み立てられるようになります。

npx skills add -y -g https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add -y -g https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets
npx skills add -y -g https://github.com/googleworkspace/cli/tree/main/skills/gws-docs

この 3 つで Drive・Sheets・Docs をカバーできます。Gmail や Calendar も使うなら同様に gws-gmail gws-calendar を追加してください。

Node.js 18 以降が必要です。Windows の場合は PowerShell や Command Prompt から同じコマンドを実行できます。

インストール後、Claude Code を再起動すれば反映されます。Claude Desktop の場合は MCP/Skill 設定ページから読み込み直してください。

試してみる

Claude にこう聞いてみます。

「Drive の最近更新したファイル 5 件を教えて」

Claude が gws drive files list を内部で叩いて結果を返してくれれば連携完了です。

トラブルシューティング

403 access_denied でログインできない

OAuth 同意画面の Test users に自分のアカウントが入っていません。3-2 の手順をやり直してください。

refresh token が 7 日で失効する

Testing mode の制約です。期限が切れたら以下を再実行すれば再認証できます。

gws auth login

本番運用するなら、Google Cloud Console で Publishing status を In production に切り替える方法もありますが、verification プロセスが必要になります。

scope を後から追加したい

gws auth login -s gmail,calendar

既存 scope を維持したまま追加されます。

scope picker で Space を押してもチェックが切り替わらない

gws のバージョンによっては picker の TUI が不安定な場合があります。その際は picker を使わず --scopes で URL を直接指定する方法が確実です。

gws auth login --scopes openid,email,profile,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/cloud-platform

picker をスキップしてブラウザの同意画面に直接進みます。

改行で分割すると scope 文字列が途中で壊れて 400: invalid_scope エラーになります。必ず 1 行で実行してください。

公式サポート対象ではない点について

gws は GitHub の googleworkspace Organization 配下にありますが、README にも明記されているとおり Google の公式プロダクトではありません（“This is not an officially supported Google product”）。Google 社員や有志が開発・メンテしているコミュニティプロジェクトという位置付けです。

実用上、次のことを意識しておくと安全です。

  • サポート窓口は GitHub Issues のみ: Google のサポートチャネルからは助けてもらえません。バグや要望は リポジトリの Issues に投げる必要があり、対応スピードは開発者の都合次第です。
  • 破壊的変更が起こり得る: v1.0 前なので、コマンド名や引数の仕様が予告なく変わる可能性があります。スクリプトに組み込む場合は Homebrew のバージョンを固定する（例: brew pin googleworkspace-cli）か、特定タグでビルドする運用にしておくと事故が減ります。
  • メンテが止まるリスクもある: コミュニティプロジェクトなのでいつ更新が止まってもおかしくありません。業務クリティカルな処理に組み込む場合は、いざというとき Google API Client Libraries を使った自前スクリプトに切り替えられるよう、抽象化しておくと安心です。

個人利用や検証目的、定型業務の自動化なら気にする必要はほぼありません。逆に 数千件/月レベルの本番バッチ や 顧客対応に直結する処理 に使うなら、上記の備えをしてから導入してください。

その他の注意事項

  • 認証情報は ~/.config/gws/（macOS/Linux）または %APPDATA%\gws\（Windows）に保存されます。OS のキーリングで暗号化されますが、PC 紛失時に備えてアカウント側でアプリ連携を解除できることを覚えておきましょう（Google アカウントのセキュリティ設定）。
  • 個人の @gmail.com ではなく Workspace（独自ドメイン）アカウントの場合、組織管理者が外部 OAuth アプリを制限している可能性があります。エラーが出たら IT 管理者に相談してください。

次のステップ

gws と Claude が繋がったら、いよいよバックオフィス業務の自動化に進めます。次回以降の記事で、請求書発行や月次経理の定型業務を Claude に任せる具体例を紹介していきます。

#Claude #Google Workspace #セットアップ #gws