MCP fork of Google Workspace CLI

gws

人間と AI エージェントのために作られた、Google Workspace 全体のための単一の CLI。
Drive、Gmail、Calendar、そしてすべての Workspace API に対応しています。定型コードは不要で、構造化された JSON 出力が得られます。40 以上のエージェントスキルを同梱しています。

メモ

これは Google が公式にサポートしている製品ではありません。

⬇️ お使いの OS 向けの最新リリースをダウンロード

gws には固定のコマンド一覧は含まれていません。実行時に Google 自身の Discovery Service を読み込み、コマンド全体を動的に構築します。Google Workspace に API エンドポイントやメソッドが追加されると、gws はそれを自動的に取り込みます。

重要

このプロジェクトは活発に開発中です。v1.0 に向けて進める過程で、破壊的変更が発生する可能性があります。

目次

• 前提条件
• インストール
• クイックスタート
• なぜ gws なのか？
• 認証
• AI エージェントスキル
• 高度な使い方
• 環境変数
• 終了コード
• アーキテクチャ
• トラブルシューティング
• 開発

前提条件

• Node.js 18+ — npm install を使う場合に必要です（または GitHub Releases からビルド済みバイナリをダウンロードしてください）。
• Google Cloud プロジェクト — OAuth 認証情報に必要です。Google Cloud Console から作成するか、gcloud CLI を使うか、gws auth setup コマンドを使って作成できます。
• Google Workspace にアクセスできる Google アカウント

インストール

gws のインストールには、推奨される方法として、GitHub Releases ページから OS とアーキテクチャに合ったビルド済みバイナリをダウンロードする方法があります。アーカイブを展開し、gws バイナリを $PATH 上に配置してください。

手軽に行うために、npm を使って GitHub Releases から適切なバイナリを自動ダウンロードすることもできます:

npm install -g @googleworkspace/cli

またはソースからビルドする場合:

cargo install --git https://github.com/googleworkspace/cli --locked

Nix フレークも github:googleworkspace/cli で利用できます。

nix run github:googleworkspace/cli

macOS と Linux では、Homebrew からもインストールできます:

brew install googleworkspace-cli

クイックスタート

gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'

なぜ gws なのか？

人間のために — REST ドキュメントに対して curl を呼び出すコードを書くのはもうやめましょう。gws なら、すべてのリソースで --help が使えるほか、--dry-run でリクエストをプレビューでき、自動ページネーションにも対応しています。

AI エージェントのために — すべてのレスポンスは構造化された JSON です。同梱のエージェントスキルと組み合わせることで、LLM はカスタムツールを用意しなくても Workspace を管理できます。

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

認証

この CLI は複数の認証ワークフローに対応しているため、ノートパソコン、CI、サーバーのいずれでも動作します。

どのセットアップを使えばよいですか？

インタラクティブ（ローカルデスクトップ）

認証情報は保存時に AES-256-GCM で暗号化されます。鍵は OS のキーリング（GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file の場合は ~/.config/gws/.encryption_key）に保存されます。

gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent scope selection and login

gws auth setup には gcloud CLI が必要です。gcloud がない場合は、代わりに下記の手動セットアップを使用してください。

警告

テストモードでのスコープ制限: OAuth アプリが未検証（テストモード）の場合、 Google は同意できるスコープを約 25 個に制限します。recommended スコーププリセットには 85 以上の スコープが含まれるため、未検証アプリでは失敗します（特に @gmail.com アカウントの場合）。 代わりに個別のサービスを選択して、スコープ選択画面を絞り込んでください。

gws auth login -s drive,gmail,sheets

手動 OAuth セットアップ（Google Cloud Console）

gws auth setup でプロジェクトやクライアントの作成を自動化できない場合、または明示的に制御したい場合に使用してください。

1. 対象のプロジェクトで Google Cloud Console を開きます:
   • OAuth 同意画面: https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • 認証情報: https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 求められた場合は、OAuth のブランディングおよびオーディエンスを設定します:
   • アプリの種類: External（テストモードのままで問題ありません）
3. Test users にご自身のアカウントを追加します
4. OAuth クライアントを作成します:
   • 種類: Desktop app
5. クライアントの JSON をダウンロードし、次の場所に保存します:
   • ~/.config/gws/client_secret.json

重要

ご自身をテストユーザーとして追加する必要があります。 OAuth 同意画面で、 Test users → Add users をクリックし、Google アカウントのメールアドレスを入力してください。これを行わないと、 汎用的な "Access blocked" エラーでログインに失敗します。

その後、次のコマンドを実行します:

gws auth login

ブラウザ支援による認証（人間またはエージェント）

OAuth は手動で完了することも、ブラウザ自動化を使って完了することもできます。

• 人間が行う場合: gws auth login を実行し、表示された URL を開いて、スコープを承認します。
• エージェント支援の場合: エージェントが URL を開き、アカウントを選択し、同意の確認を処理し、localhost のコールバックが成功すると制御を戻します。

同意画面に "Google hasn't verified this app"（テストモード）と表示された場合は、Continue をクリックします。 スコープのチェックボックスが表示された場合は、必要なスコープを選択（または Select all）してから続行します。

ヘッドレス / CI（エクスポートフロー）

1. ブラウザのあるマシンでインタラクティブな認証を完了します。
2. 認証情報をエクスポートします:

   gws auth export --unmasked > credentials.json
   

3. ヘッドレスマシンで次を実行します:

   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
   gws drive files list   # just works
   

サービスアカウント（サーバー間）

キーファイルを指定します。ログインは不要です。

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

取得済みのアクセストークン

別のツール（例: gcloud）がすでに環境用のトークンを発行している場合に便利です。

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

優先順位

環境変数は .env ファイルに記述することもできます。

AI エージェントスキル

このリポジトリには 100 以上の Agent Skills（SKILL.md ファイル）が含まれています。サポートされている API ごとに 1 つずつあるほか、一般的なワークフロー向けの高レベルなヘルパーや、Gmail、Drive、Docs、Calendar、Sheets 向けの 50 個の厳選されたレシピがあります。完全な一覧は スキル一覧 を参照してください。

# Install all skills at once
npx skills add https://github.com/googleworkspace/cli

# Or pick only what you need
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

# Symlink all skills (stays in sync with repo)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

1. まず、CLI で認証を行います:

   gws auth setup
   

2. Gemini CLI に拡張機能をインストールします:

   gemini extensions install https://github.com/googleworkspace/cli
   

この拡張機能をインストールすると、Gemini CLI エージェントから gws のすべてのコマンドと Google Workspace エージェントスキルに直接アクセスできるようになります。gws は認証を安全に処理するため、エージェントを使用する前にターミナルで一度認証するだけで済み、拡張機能が認証情報を自動的に引き継ぎます。

高度な使い方

マルチパートアップロード

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

ページネーション

Google スプレッドシート — シェルのエスケープ

スプレッドシートの範囲指定には ! が含まれますが、bash はこれを履歴展開として解釈します。値は必ずシングルクォートで囲んでください:

# Read cells A1:C10 from "Sheet1"
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

ヘルパーコマンド

一部のサービスでは、自動生成された Discovery のインターフェースに加えて、手作業で作成されたヘルパーコマンドを提供しています。ヘルパーコマンドには + の接頭辞が付いており、見分けやすく、Discovery で生成されるメソッド名と衝突することもありません。

時間を考慮するヘルパー (+agenda、+standup-report、+weekly-digest、+meeting-prep) は、Google アカウントのタイムゾーン (Calendar Settings API から取得し、24 時間キャッシュ) を自動的に使用します。+agenda では --timezone/--tz で上書きでき、明示的に制御するには --timezone フラグを設定します。

gws <service> --help を実行すると、Discovery のメソッドとヘルパーコマンドをまとめて確認できます。

gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
gws calendar --help   # shows +insert, +agenda …
gws drive --help      # shows +upload …

ヘルパーコマンドの完全なリファレンス:

例:

# Send an email
gws gmail +send --to [email protected] --subject "Hello" --body "Hi there"

# Reply to a message
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Append a row to a spreadsheet
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# Show today's calendar agenda
gws calendar +agenda

# Upload a file to Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# Morning standup summary
gws workflow +standup-report

# Show today's agenda in a specific timezone
gws calendar +agenda --today --timezone America/New_York

Model Armor（レスポンスのサニタイズ）

Google Cloud Model Armor を統合し、API レスポンスがエージェントに届く前にプロンプトインジェクションがないかスキャンします。

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

環境変数

すべての変数は省略可能です。コピーして使えるテンプレートは .env.example を参照してください。

環境変数は dotenvy で読み込まれる .env ファイルに設定することもできます。

終了コード

gws は構造化された終了コードを使用するため、スクリプトはエラー出力を解析することなく、失敗の種類に応じて処理を分岐できます。

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 — API error

gws unknown-service files list
echo $?   # 3 — validation error (unknown service)

アーキテクチャ

gws は 2 段階の解析 戦略を使用します。

1. argv[1] を読み取り、サービス（例: drive）を特定する
2. サービスの Discovery Document を取得する（24 時間キャッシュ）
3. ドキュメントのリソースとメソッドから clap::Command ツリーを構築する
4. 残りの引数を再解析する
5. 認証し、HTTP リクエストを構築して実行する

成功、エラー、ダウンロードのメタデータを含むすべての出力は、構造化された JSON です。

トラブルシューティング

ログイン時の「Access blocked」または 403

OAuth アプリが テストモード になっており、お使いのアカウントがテストユーザーとして登録されていません。

対処法: GCP プロジェクトで OAuth 同意画面 を開き、テストユーザー → ユーザーを追加 の順に進み、Google アカウントのメールアドレスを入力します。その後、gws auth login を再実行してください。

「Google はこのアプリを検証していません」

アプリがテストモードの場合には想定どおりの表示です。詳細 → <アプリ名> (安全でないページ) に移動 をクリックして続行します。個人利用であれば安全です。検証が必要になるのは、アプリを他のユーザーに公開する場合だけです。

スコープが多すぎる / 同意画面のエラー

未検証（テストモード）のアプリは、OAuth スコープが約 25 個までに制限されています。recommended スコーププリセットには多くのスコープが含まれるため、この上限を超えてしまいます。

対処法: 必要なスコープのみを選択してください。

gws auth login --scopes drive,gmail,calendar

gcloud CLI が見つからない

gws auth setup は、プロジェクト作成を自動化するために gcloud CLI を必要とします。対処方法は次の 3 つです。

1. gcloud をインストール し、gcloud を直接使用する。
2. gcloud の呼び出しをラップしている gws auth setup を再実行する。
3. gcloud を使わずに済ませる。Cloud Console で OAuth 認証情報を手動で設定する。

redirect_uri_mismatch

OAuth クライアントが デスクトップアプリ タイプで作成されていません。認証情報ページで既存のクライアントを削除し、タイプ デスクトップアプリ で新しいクライアントを作成して、新しい JSON をダウンロードしてください。

API が有効になっていない — accessNotConfigured

必要な Google API が GCP プロジェクトで有効になっていない場合、理由 accessNotConfigured を含む 403 エラーが表示されます:

{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

gws は、対処方法のヒントを stderr にも出力します:

💡 API not enabled for your GCP project.
   Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   After enabling, wait a few seconds and retry your command.

修正手順:

1. enable_url のリンクをクリックします（または enable_url JSON フィールドからコピーします）。
2. GCP コンソールで 有効にする をクリックします。
3. 約 10 秒待ってから、gws コマンドを再実行します。

ヒント

gws auth setup を実行することもできます。プロジェクトに必要なすべての API を有効にする手順を自動で案内してくれます。

開発

cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/

ライセンス

Apache-2.0

免責事項

注意

これは Google の公式にサポートされた製品ではありません。