Google Workspace CLI（gws）を使ってみた ─ Gmail・Drive・Calendar をコマンド一発で操作

はじめに

2026年3月4日、Google が Google Workspace CLI（gws） を OSS（Apache 2.0）で公開しました。Gmail、Google Drive、Calendar、Sheets、Docs、Chat、Admin ─── Google Workspace のほぼすべてのサービスを、コマンドラインから操作できるツールです。

公開直後から話題になった理由は、単なる CLI ツールではないからです。gws は AI エージェントとの連携を前提に設計されています。全レスポンスが構造化 JSON で返り、100以上の Agent Skills（SKILL.md）ファイルが同梱され、MCP サーバー機能も内蔵。Claude Code や Gemini CLI から Google Workspace を直接操作できる未来が、もうすぐそこまで来ています。

今回は第1回として、gws のインストールから OAuth 認証セットアップ、そして実際に Gmail・Drive・Calendar を操作するところまでを解説します。

gws とは？

gws は Google が GitHub と npm で公開した Workspace API の CLI ツールです。主な特徴をまとめます。

技術的に面白いのは、gws が コマンドを静的に持っていない 点です。起動時に Google Discovery Service から API 仕様をリアルタイムで取得し、コマンドを動的に生成します。つまり Google が新しい API を追加すれば、gws も自動的にその API を使えるようになります。

インストール

Node.js（npm）がインストールされていれば、1コマンドでインストールできます。

npm install -g @googleworkspace/cli

バージョン確認：

$ gws --version
gws 0.7.0
This is not an officially supported Google product.

OAuth 認証のセットアップ

gws を使うには Google Cloud の OAuth 認証が必要です。gws auth setup コマンドで、GCP プロジェクトの作成から API の有効化まで一括でセットアップできます。

gws auth setup

このコマンドは以下を自動で行います：

1. gcloud CLI の検出 ─ 事前に gcloud がインストールされている必要があります
2. GCP プロジェクトの選択 ─ 既存プロジェクトを使うか、新規作成
3. Workspace API の有効化 ─ Drive、Gmail、Calendar 等 13 個の API を一括有効化
4. OAuth クライアントの設定 ─ Client ID と Client Secret の入力

OAuth 同意画面の設定

Step 5 の OAuth credentials で「Manual OAuth client setup required」と表示されます。

ここで GCP コンソールでの設定が必要になります。画面に表示される URL を開き、以下の手順で進めます。

Step A: OAuth 同意画面（ブランディング）の作成

Google Auth Platform の概要画面で「開始」をクリックします。

ブランディングの作成フォームが表示されます。入力するのはたった2つだけです：

• アプリ名: gws と入力（自分しか使わないので何でもOK）
• ユーザーサポートメール: 自分のメールアドレスを選択

「次へ」で対象を選択する画面になります。「外部」 を選びます。

連絡先情報にメールを入力し、「作成」で完了です。GCP コンソールの設定が面倒に見えますが、実質はアプリ名とメールを入れるだけです。

Step B: OAuth クライアント ID の作成

左メニューの「クライアント」→「OAuth クライアント ID の作成」に進みます。

• アプリケーションの種類: 「デスクトップアプリ」を選択
• 名前: デフォルトのままでOK
• 「作成」をクリック

表示された Client ID と Client Secret をターミナルに貼り付ければ、setup は完了です。

ログイン（OAuth 認証）

setup が完了したら、ログインします。

gws auth login

ブラウザが開き、OAuth スコープの選択画面が表示されます。Recommended (Core Consumer Scopes) を選択すれば、Drive・Gmail・Calendar・Docs・Sheets・Tasks の権限がまとめて付与されます。

Google の権限許可画面で「許可」をクリックします。

認証が完了すると、認証情報が AES-256-GCM で暗号化されて OS のキーリングに保存されます。

実際に使ってみる

認証が完了したので、実際に Google Workspace を操作してみましょう。

Google Drive ─ ファイル一覧を取得

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

ドキュメント、スプレッドシート、プレゼンテーション ─── Drive 内のファイルが JSON 形式で返ってきます。mimeType でファイルの種類がわかり、id を使えば個別のファイルにアクセスできます。

Gmail ─ メールの内容を取得

gws gmail users messages get \
    --params '{"userId": "me", "id": "<メッセージID>", "format": "metadata"}'

メール一覧の取得はもちろん、個別メッセージの件名・送信者・日時などのメタデータも取得できます。format パラメータで取得する情報量を制御可能です。

Google Calendar ─ 予定一覧を取得

gws calendar events list \
    --params '{"calendarId": "primary", "maxResults": 3, "singleEvents": true}'

カレンダーの予定が構造化された JSON で返ります。summary（予定名）、start / end（開始・終了時刻）が明確に構造化されているため、プログラムからの処理が容易です。

全レスポンスが JSON ─ なぜこれが重要か

gws の全レスポンスが構造化 JSON であることは、AI エージェント連携において決定的に重要です。

• パース不要: AI がそのまま読み取れる
• jq で加工可能: gws drive files list | jq '.files[].name' でファイル名だけ抽出
• パイプライン構築: 他のコマンドと組み合わせて自動化フローを構築可能

これは「人間のための CLI」と「AI のための API」を1つのインターフェースで両立させるという設計思想の表れです。

まとめ

Google Workspace CLI（gws）を実際にインストールし、Gmail・Drive・Calendar をコマンドラインから操作してみました。

やったこと：

• gws のインストール（npm install -g @googleworkspace/cli）
• GCP コンソールで OAuth 認証のセットアップ
• Drive のファイル一覧、Gmail のメッセージ取得、Calendar の予定一覧

感じたこと：

• OAuth 設定は初回だけ面倒だが、一度セットアップすれば快適
• 全レスポンスが JSON なので、スクリプトや AI との相性が抜群
• v0.7.0 でこの完成度は期待が持てる

gws の真価は、実は今回触れていない Agent Skills と MCP サーバー にあります。100以上の SKILL.md ファイルが同梱されており、Claude Code や Gemini CLI から自然言語で Google Workspace を操作できるようになります。

次回は、この Agent Skills を Claude Code にインストールして、「明日の予定を教えて」「最新のメールをまとめて」といった自然言語での操作を実演します。お楽しみに。