mcpField
G
gws

gws

github.com/glebis生産性401231 回インストール1 日前に更新
リポジトリ

gws について

gws は Google Workspace の各サービスを操作するコマンドラインツールです。メール、カレンダー、ファイル、ドキュメントなどの管理に使え、サービス横断ワークフローと複数の出力形式も備えています。

主な機能

  1. 01Gmail、Calendar、Drive などを操作
  2. 02メール、予定、ファイル用のヘルパーコマンド
  3. 03サービス横断ワークフロー
  4. 04JSON、表、YAML、CSV 出力
  5. 05ページネーション、アップロード、ダウンロード

活用シーン

  1. 01未読メールの確認とメール送信
  2. 02予定の確認やカレンダーイベントの作成
  3. 03ファイルのアップロードと Sheets の読み書き
  4. 04会議と未完了タスクの要約

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/glebis/claude-skills --skill gws

インストール後、Claude Code で/gwsを入力して読み込まれたか確認します。

同梱ファイル.claude-plugin/plugin.jsonreferences/api_reference.md

詳細

Google Workspace CLI (gws)

Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks、People、Chat、Meet、Forms、Keep、Admin、およびサービス横断ワークフロー用の CLI です。

バイナリ：/opt/homebrew/bin/gws

コマンドの形式

gws <service> <resource> [sub-resource] <method> [flags]

すべてのコマンドで以下を指定できます。

  • --params <JSON> — URL／クエリパラメーター
  • --json <JSON> — リクエスト本文（POST/PATCH/PUT）
  • --upload <PATH> — メディアコンテンツとしてアップロードするファイル
  • --output <PATH> — バイナリレスポンス（ダウンロード）の保存先
  • --format json|table|yaml|csv — 出力形式（デフォルト：json）
  • --page-all / --page-limit N — 自動ページネーション
  • --dry-run — 送信せずにローカルで検証

クイックリファレンス — ヘルパーコマンド（こちらを優先してください）

コマンド用途R/W
gws gmail +triage [--max N] [--query Q]未読受信トレイの概要R
gws gmail +send --to EMAIL --subject S --body Tプレーンテキストメールを送信W
gws gmail +watch --project GCP新着メールをストリーミング（Pub/Sub）R
gws calendar +agenda [--today|--tomorrow|--week|--days N]今後の予定R
gws calendar +insert --summary T --start ISO --end ISO予定を作成W
gws drive +upload FILE [--parent ID] [--name N]ファイルをアップロードW
gws sheets +read --spreadsheet ID --range R範囲を読み取る（例：Sheet1!A1:D10）R
gws sheets +append --spreadsheet ID --values "a,b,c"行を追加（または --json-values）W
gws docs +write --document ID --text Tドキュメントにテキストを追記W
gws chat +send --space spaces/ID --text TChat のスペースに投稿W
gws workflow +standup-report今日の会議と未完了のタスクR
gws workflow +meeting-prep [--calendar ID]次の会議の詳細R
gws workflow +email-to-task --message-id IDメール → タスクW
gws workflow +weekly-digest今週の会議と未読メールR
gws workflow +file-announce --file-id ID --space SPACEChat でファイルを告知W

よく使うパターン

Gmail
# Triage unread (table for humans)
gws gmail +triage --max 10 --format table

# Search
gws gmail users messages list --params '{"userId":"me","q":"from:amazon newer_than:7d","maxResults":5}'

# Read full message
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"full"}'

# Read headers only (faster)
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"metadata","metadataHeaders":["Subject","From","Date"]}'

# Archive (remove INBOX)
gws gmail users messages modify --params '{"userId":"me","id":"MSG_ID"}' --json '{"removeLabelIds":["INBOX"]}'

# Trash
gws gmail users messages trash --params '{"userId":"me","id":"MSG_ID"}'

# Bulk label
gws gmail users messages batchModify --params '{"userId":"me"}' --json '{"ids":["ID1","ID2"],"addLabelIds":["Label_123"]}'
Calendar
# Today (Europe/Berlin default works with RFC3339 +02:00/+01:00)
gws calendar +agenda --today --format table

# Create simple event
gws calendar +insert \
  --summary 'AGENCY Meetup' \
  --start '2026-04-14T18:00:00+02:00' \
  --end '2026-04-14T19:00:00+02:00' \
  --location 'https://us02web.zoom.us/j/8991032224' \
  --description 'Zoom: https://us02web.zoom.us/j/8991032224'

# Event WITH Google Meet link (helper doesn't support — use raw)
gws calendar events insert \
  --params '{"calendarId":"primary","conferenceDataVersion":1}' \
  --json '{
    "summary":"Sync",
    "start":{"dateTime":"2026-04-15T14:00:00+02:00"},
    "end":{"dateTime":"2026-04-15T15:00:00+02:00"},
    "conferenceData":{"createRequest":{"requestId":"req-'$(date +%s)'","conferenceSolutionKey":{"type":"hangoutsMeet"}}}
  }'

# Update event
gws calendar events patch --params '{"calendarId":"primary","eventId":"EID"}' --json '{"summary":"New title"}'

# Delete
gws calendar events delete --params '{"calendarId":"primary","eventId":"EID"}'

# List all calendars
gws calendar calendarList list --format table
Drive
# Upload to root
gws drive +upload ./report.pdf

# Upload to folder
gws drive +upload ./data.csv --parent FOLDER_ID --name 'Sales Data.csv'

# Search files
gws drive files list --params '{"q":"name contains \"report\" and mimeType=\"application/pdf\"","pageSize":10}'

# Download
gws drive files get --params '{"fileId":"FID","alt":"media"}' --output ./local.pdf

# Create folder
gws drive files create --json '{"name":"MyFolder","mimeType":"application/vnd.google-apps.folder"}'

# Share with user
gws drive permissions create --params '{"fileId":"FID"}' --json '{"role":"reader","type":"user","emailAddress":"[email protected]"}'
Sheets
# Read
gws sheets +read --spreadsheet SID --range 'Sheet1!A1:D10' --format table

# Append single row (simple values)
gws sheets +append --spreadsheet SID --values 'Alice,100,true'

# Append multiple rows
gws sheets +append --spreadsheet SID --json-values '[["a","b"],["c","d"]]'
Tasks
gws tasks tasklists list
gws tasks tasks list --params '{"tasklist":"@default"}'
gws tasks tasks insert --params '{"tasklist":"@default"}' --json '{"title":"My task","notes":"Details","due":"2026-04-20T00:00:00Z"}'
gws tasks tasks patch --params '{"tasklist":"@default","task":"TID"}' --json '{"status":"completed"}'
Chat
# Find space
gws chat spaces list --format table

# Post message
gws chat +send --space spaces/AAAAxxxx --text 'Hello team!'
People / Contacts
gws people people connections list --params '{"resourceName":"people/me","personFields":"names,emailAddresses","pageSize":100}'
gws people people searchContacts --params '{"query":"John","readMask":"names,emailAddresses"}'

重要な注意事項

  • userId：Gmail の raw 呼び出しでは、すべての params に "userId":"me" が必要です。
  • RFC3339 時刻：Calendar ではオフセットを含む完全な ISO 形式を使用します（2026-04-14T18:00:00+02:00）。UTC には「Z」を使用します。
  • Meet リンク：+insert では会議用リンクは追加されません。conferenceDataVersion=1 および conferenceData.createRequest を指定して、raw の events.insert を使用してください。
  • ページネーション：--page-all は NDJSON（ページごとに 1 つの JSON オブジェクト）を出力します。--page-limit N はページ数の上限を設定します。
  • スキーマの確認：gws schema <service>.<resource>.<method> を使用します（例：gws schema gmail.users.messages.list）。
  • フィルター：gmail.settings.basic スコープが必要です。特別な手動 OAuth フローを使用してください（references/api_reference.md を参照）。
  • 書き込みの確認：+send、+insert、+email-to-task、+file-announce、drive files delete、events delete、messages trash の実行前には、必ずユーザーに確認してください。
  • 形式の選択：人が読みやすい概要には --format table を使用します。スクリプトや jq へのパイプでは、デフォルトの json を使用します。

OAuth の設定

  • GCP プロジェクト：n8n-automations-454016
  • 認証情報：~/.config/gws/credentials.json
  • 設定済みスコープ：gmail.modify、gmail.settings.basic、drive、spreadsheets、tasks、calendar、documents、chat.messages、contacts.readonly
  • gmail.settings.basic スコープには手動 OAuth が必要です（ポート 8085 で Python の localhost リスナーを使用）。gws auth login --scopes から直接リクエストすることはできません。

API リファレンス全文

コマンド一覧、すべての raw API 呼び出し、ページネーション、ラベル、下書き、フィルター、Admin API については、references/api_reference.md を参照してください。

コメント

Markdown 対応