Markdown版
AI-translated from English; not yet reviewed by a fluent editor.
# 5つの読み取り確認で Claude Code を Google Workspace に接続する
> 範囲を絞った Drive、Sheets、Docs、Gmail の読み取りを使い、Claude Code が利用する Google Workspace CLI のアカウント、OAuth の許可、権限確認を調べる文書ベースの手順。
By BIG CHANGE Editorial
Published: 2026-10-20T09:34:40.461Z
Updated: 2026-10-20T09:34:40.461Z
Canonical: https://bigchange.ai/blog/claude-code-google-workspace-cli-read-checks
AI-generated conceptual illustration by BIG CHANGE.
Claude Code はローカルシェルから Google Workspace CLI（`gws`）のコマンドを実行でき、`gws` で認証した Google アカウントを使用します。権限を持つアカウント所有者は、Drive、Sheets、Docs、Gmail にそれぞれ用意した無害なデータ1件で接続を確認できます。最初にアカウントと許可を確認してください。本ガイドは2026年10月20日に確認した CLI リポジトリの文書化されたインターフェースに従います。BIG CHANGE はどちらのツールもインストールしておらず、アカウントにもアクセスしていません。
## 大きな変化
- **変わったこと：** 現在の `gws` CLI は、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 向けのリポジトリのリリース](https://github.com/googleworkspace/cli/releases)からインストールするか、Node.js 18以降があれば文書記載のコマンドを使います。
```bash
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つのスコープを明示的に要求します。
```bash
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 検索式内のアポストロフィをエスケープします。
```bash
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 とタブ名を使い、既知のセルを読み取ります。
```bash
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'
```
返された値を表と比較します。Google は末尾の空セルを省略する場合があるため、空ではない既知の値を用意します。
短いテスト文書の最初のタブを読み取ります。
```bash
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つのヘッダーを要求します。
```bash
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 | 一覧でテストメールが見つかり、メタデータ取得でその `Message-ID` と件名が一致する。 |
バージョン、認証済みアカウント、実際の許可、対象 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 アドオン](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) は、別の経路で、承認を得て開いているファイルを編集する機能を扱っています。
## Sources
- [Google Workspace CLI の README](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — 2026年10月20日に調べた、特定コミットの公式リポジトリ。インストール、手動 OAuth 設定、動的コマンド、認証情報の優先順位、版の不安定さ、公式サポート対象外の注意書きを示します。BIG CHANGE の実行結果を示すものではありません。
- [Google Workspace CLI のコマンド文脈](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — 入れ子のメソッド、--params、スキーマ確認、限定したフィールド選択に関する特定コミットの公式ガイド。実際にインストールしたヘルプの確認が必要です。
- [Google Workspace CLI の認証実装](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — 固定した認証ソースは、独自の --scopes、別個のサービス選択動作、追加される識別スコープを確認できます。ソースを調べても読者の実際の許可は分かりません。
- [Google Workspace API の有効化ガイド](https://developers.google.com/workspace/guides/enable-apis) — Cloud プロジェクトで API を有効にする Google の手順。アクセスには引き続きプロジェクトと管理者の方針が適用されます。
- [Drive files.list リファレンス](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — メタデータ検索を制限する Drive q、pageSize、応答フィールドを確認できます。狭い要求でも OAuth 権限は縮小しません。
- [Sheets spreadsheets.values.get リファレンス](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — スプレッドシート ID と A1 範囲による読み取り、応答形式を確認できます。末尾の空セルは省略される場合があります。
- [Docs documents.get リファレンス](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — 文書取得と、includeTabsContent が false の場合に最初のタブだけを対象とする制約を確認できます。例は、タブ1つのプレーンテキストのテスト文書向けです。
- [Gmail messages.list と messages.get のリファレンス](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — list の文書はメール ID による検索と ID だけの一覧結果を説明します。gmail.metadata では q を使えません。対応する get の文書は https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get で、METADATA 形式の metadataHeaders を説明します。
- [Claude Code の権限](https://code.claude.com/docs/en/permissions) — Manual/default モード、Ask 規則、実効ツール権限、シェル承認確認に関する Anthropic の現行文書。読者の特定セッションに特定の規則があることを示すものではありません。
BIG CHANGEニュースレター
大局を、あなたのペースで。
AI とロボティクスの最新記事、注目すべき変化、活用できる実用的なアイデア。日刊ブリーフィング、週刊ダイジェスト、月刊展望から選べます。
Next scheduled send (UTC): . Your first edition arrives at the next scheduled send after you confirm.