Claude Code はローカルシェルから Google Workspace CLI（gws）のコマンドを実行でき、gws で認証した Google アカウントを使用します。権限を持つアカウント所有者は、Drive、Sheets、Docs、Gmail にそれぞれ用意した無害なデータ1件で接続を確認できます。最初にアカウントと許可を確認してください。本ガイドは2026年10月20日に確認した CLI リポジトリの文書化されたインターフェースに従います。BIG CHANGE はどちらのツールもインストールしておらず、アカウントにもアクセスしていません。
大きな変化
- 変わったこと： 現在の
gwsCLI は、Google Workspace API のメソッドを Claude Code が実行できるシェルコマンドとして提供します。認証済みアカウント1つで複数の業務サービスに接続できますが、実際の許可とエージェントのシェル権限に制約されます。 - 重要な理由： 選択したファイルやメールを確認できる接続は、OAuth スコープが対象とするほかのデータにもアクセスできる場合があります。アカウント所有者は、既知の少量の結果をターミナルと Claude Code で比較してから、さらに作業を委ねるか判断できます。
- 注意点： 設定が変わるたびに、インストール済み CLI が生成するコマンドと、セッションで実際に有効な権限規則を確認してください。CLI はまだ1.0より前の版です。狭いサンプルクエリやフィールドマスクで、アカウント全体に対する許可が縮小するわけではありません。
接続前の準備
機密情報のない、承認済みの専用 Google テストアカウントと、OAuth を設定する権限のある Cloud プロジェクトを使用します。4つの API と要求する許可が認められるか管理者に確認してください。固有の名前を持つ既存の Drive ファイル、小さな範囲に既知の値を置いたスプレッドシート、タブ1つの短いプレーンテキスト Google Doc、無害な Gmail メールを用意します。Gmail については、メールの RFC Message-ID を Show original から取得します。これらの元データを CLI の結果と比較します。この確認で何かを作成したり送信したりすることはありません。
管理されたコンピューターに Claude Code をインストールします。gws は、使用する OS 向けのリポジトリのリリースからインストールするか、Node.js 18以降があれば文書記載のコマンドを使います。
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --helpインストール済み CLI と Claude Code のバージョンを非公開で記録します。CLI はまだ1.0より前で、コマンドは Google の API ディスカバリ文書から生成されます。例を実行する前に、インストール済みのヘルプと以下のメソッドスキーマを確認してください。
1. 範囲を絞った OAuth ログインを設定する
承認済み Cloud プロジェクトで Drive、Sheets、Docs、Gmail の API を有効にします。OAuth の対象を設定し、Desktop app クライアントを作成します。アプリが External でテスト中なら、選択したアカウントをテストユーザーに追加します。ダウンロードしたクライアント JSON を文書記載の ~/.config/gws/client_secret.json の場所に保存するか、GOOGLE_WORKSPACE_CLI_CONFIG_DIR で指定した別のディレクトリを使います。そのディレクトリは Claude プロジェクトの外に置き、アカウント所有者だけがアクセスできるようにします。
ログイン前に、GOOGLE_WORKSPACE_CLI_TOKEN または GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE が設定されていないか、.env ファイルによる設定も含めて非公開で確認します。これらは保存済み OAuth 認証情報より優先されます。値を表示したり、Claude Code に認証情報ファイルを読ませたりしないでください。余計な設定のない環境と、意図したクライアント設定を使います。
次の4つのスコープを明示的に要求します。
gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth statusアカウント選択と同意は自分で行います。固定した版の CLI ソースは、識別用のスコープ openid、userinfo.email、userinfo.profile も追加します。同意画面と gws auth status のアカウント、許可、トークン有効性を意図した内容と非公開で比較します。状態フィールドがなければ未検証のままです。アカウントが違う、または予想外の広い許可が残っていれば停止します。ログイン時のサービス選択は候補を絞るもので、この4つの読み取り専用スコープを設定する機能ではありません。
スコープはサンプル要求より広いものです。Drive メタデータ権限はアクセス可能なファイルのメタデータ、Sheets と Docs の読み取り専用権限はアクセス可能な表や文書を対象とし、Gmail の読み取り専用権限はメールボックスの内容にアクセスできます。名前、ID、セル範囲、クエリ、フィールドマスクが制限するのは個々の応答であり、トークンの権限ではありません。シェルツールはローカルの認証情報にも届く場合があるため、ファイルパスを隠したりプロンプトで指示したりするだけでは隔離できません。
2. 範囲を絞った読み取りを直接実行する
まず各メソッドを gws schema drive.files.list で確認し、ほかのメソッドには対応するスキーマ名を使います。インストール済み版でパラメーターが違う場合は、生成された --help を確認します。以下は Bash の単一引用符の構文です。別のシェルでは引用符を意識して調整してください。置き換えるのはテスト用の識別子と名前だけです。1つずつ実行し、実際の応答またはエラーを、トークンや機密内容を除いて非公開で保存します。
指定した名前の Drive ファイルを探します。JSON の \u0027 は、Bash の引用符を保ちながら Drive 検索式内のアポストロフィをエスケープします。
gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'返された ID と名前を Drive のファイルと比較します。一致がない場合や incompleteSearch がある場合、意図したファイルへのアクセスを確認できたことにはなりません。
実際のスプレッドシート ID とタブ名を使い、既知のセルを読み取ります。
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'返された値を表と比較します。Google は末尾の空セルを省略する場合があるため、空ではない既知の値を用意します。
短いテスト文書の最初のタブを読み取ります。
gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'ID、タイトル、既知の文章を照合します。この限定的な応答では、ほかのタブ、コメント、文書構造全体は確認しません。
Gmail では、既存メールの RFC Message-ID で検索し、返された Gmail ID を使って2つのヘッダーを要求します。
gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'返された Message-ID と無害な件名を元メールと比較します。最初の呼び出しが返すのはメール ID であり、ヘッダーではありません。2番目はヘッダーメタデータを要求し、本文は要求しません。最初の応答が空なら2番目の確認はできません。より狭い Gmail メタデータ OAuth スコープでは、この検索クエリは使えません。明示的な Gmail 読み取り専用許可では使用できます。
3. 権限確認付きで Claude Code から繰り返す
自分が管理するプロジェクトで、同じ承認済みアカウント設定を使って Claude Code を起動します。/permissions で有効なモードとシェル規則を確認します。Manual（default とも呼ばれます）と、実際のシェルツールに対する Ask 規則を使います。より広い許可や回避規則は組織の方針に従って解消してください。gws * やシェルのラッパーに対する一括承認は避けます。提案されたコマンドは毎回全体を確認し、意図した範囲の読み取りだけを承認します。
Claude Code に通常の言葉で、同じテスト対象を使って上の5つのコマンドを提案し、自分が権限を判断した後に1つずつ実行するよう依頼します。認証情報の読み取り、クエリの拡張、書き込みは行わず、出力またはエラーを報告するよう求めます。その後、各結果を直接実行の結果と元の対象の両方と比較します。プロジェクトの指示には作業を記述できますが、アクセスを決めるのは実効的なツール権限と OAuth の許可です。
サービス | 両方の経路で必要な完了証拠 |
|---|---|
Drive | 同じファイル ID と名前。検索が完了している。 |
Sheets | 期待するタブ、範囲、既知のセル値。 |
Docs | 期待する ID、タイトル、最初のタブの文章。 |
Gmail | 一覧でテストメールが見つかり、メタデータ取得でその |
バージョン、認証済みアカウント、実際の許可、対象 ID、直接実行の結果、Claude の結果、エラーを非公開の確認表に記録します。失敗した要求、成功したが空の応答、検証済みの対象は異なる結果です。4つのサービスすべてを両経路で検証したときだけ完了とします。
確認に失敗した場合
ログイン時の Access blocked は、テストアカウントが OAuth アプリのテストユーザー一覧にないことを示す場合があります。API やスコープのエラーでは、有効な API、選択したアカウント、実際の許可を確認してから、承認済みの再同意を求めます。一覧が空なら正確な対象、クエリ、アカウントを確認します。インストール済みヘルプが例と違う場合は、先に現在のメソッドスキーマを使います。Claude Code が変更操作や広いコマンドを提案したら権限確認で拒否し、限定的な読み取りに戻ります。
CLI リポジトリは有料パッケージなしで利用できます。アカウントや Workspace プラン、Cloud の割り当て、Claude Code プランや API 使用には費用が発生する場合があります。取得内容は Claude Code に設定したプロバイダーで処理される可能性があるため、承認済みの非機密テストデータだけを使います。CLI は Google の公式サポート製品ではないと明記し、1.0以前の変更を警告しています。BIG CHANGE は性能や互換性をテストしていません。書き込み、送信、アカウント変更の前に停止してください。Claude の別の Google Workspace アドオン は、別の経路で、承認を得て開いているファイルを編集する機能を扱っています。
