Google Workspace CLI (gws)

---

name: gws description: Google Workspace CLI (official Google release) for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every Workspace API. Includes native MCP server mode for AI agents. Use when you need to manage Google Workspace services via CLI or expose them as MCP tools. license: MIT homepage: https://github.com/googleworkspace/cli metadata: { "openclaw": { "emoji": "🏢", "requires": { "bins": ["gws"] }, "install": [ { "id": "npm", "kind": "npm", "package": "@googleworkspace/cli", "global": true, "bins": ["gws"], "label": "Install gws (npm)", }, ], }, }

---

gws — Google Workspace CLI

Official Google-published CLI for all Workspace APIs. Dynamically built from Google Discovery Service — covers every API endpoint automatically as Google adds them.

Note: This is the official Google-org CLI (googleworkspace/cli), distinct from third-party alternatives. Prefer gws for new integrations — it has native MCP mode and active development from Google.

---

APIs Covered

Drive — files, folders, sharing, permissions

Gmail — messages, labels, drafts, send

Calendar — events, calendars, invites

Sheets — spreadsheets, values, formatting

Docs — documents read/write

Chat — spaces, messages

Admin — users, groups, org units

Tasks — task lists, tasks

Meet — meeting resources

*...and every other Workspace API via Discovery Service*

---

Installation

npm install -g @googleworkspace/cli
or: cargo install --git https://github.com/googleworkspace/cli --locked
or: nix run github:googleworkspace/cli

Verify:

gws --version

---

Authentication (One-time Setup Required)

⚠️ Auth requires manual action — OAuth credentials must be set up once per account.

Option A: With gcloud (fastest)

gws auth setup   # creates GCP project, enables APIs, logs in
gws auth login   # subsequent logins / scope changes

Option B: Without gcloud (manual GCP console)

1. Go to console.cloud.google.com → create project 2. Enable Workspace APIs (Drive, Gmail, Calendar, etc.) 3. Create OAuth 2.0 Client ID (Desktop app type) 4. Download credentials JSON 5. Set: export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json 6. Run: gws auth login

Option C: Service Account (server/headless)

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json

Credentials are encrypted at rest (AES-256-GCM) with OS keyring.

---

Basic Usage

# List 10 most recent Drive files
gws drive files list --params '{"pageSize": 10}'
Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
List Gmail messages
gws gmail users messages list --params '{"userId": "me", "maxResults": 5}'
Send a Gmail message
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": ""}'
Inspect any method schema
gws schema drive.files.list
Stream paginated results
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
Dry-run (preview request without executing)
gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "test"}' --dry-run

---

MCP Server Mode (AI Agent Use)

gws can act as an MCP server, exposing all Workspace APIs as structured tools for Claude, Cursor, VS Code, etc.

# Start MCP server (all services)
gws mcp
Start MCP server (specific services only — recommended)
gws mcp -s drive,gmail,calendar
Compact mode — reduces from 200-400 tools to ~26 meta-tools (saves context)
gws mcp -s drive,gmail,calendar --tool-mode compact

Add to your agent config (e.g. OpenClaw / mcporter):

{
  "mcpServers": {
    "google-workspace": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs", "--tool-mode", "compact"]
    }
  }
}

---

OpenClaw Agent Usage

After auth setup, the agent can:

Read/send Gmail → automate email workflows

Read/write Calendar → schedule meetings, parse availability

Read/write Sheets → log data, pull reports

Manage Drive → organize files, share docs

Chat → send notifications to Google Chat spaces

Example — list recent emails:

gws gmail users messages list --params '{"userId": "me", "maxResults": 10, "q": "is:unread"}'

---

Notes

Auth is manual (one-time) — must complete gws auth setup before first use

Active development — pre-v1.0, expect breaking changes; check GitHub for latest

Official Google org — published by googleworkspace on GitHub, not a third-party

No boilerplate — structured JSON output, works with jq and scripts

MCP-native — expose any Workspace API as an MCP tool with a single command

---

Status

Viability: ✅ HIGH — official Google org, MCP-native, npm installable

Auth blocker: ⚠️ Manual one-time gws auth setup required (GCP project needed)

Replacement: Better long-term choice vs. gcloud scripting — auto-updates with Google API surface

Auth is manual (one-time) — must complete gws auth setup before first use

Active development — pre-v1.0, expect breaking changes; check GitHub for latest

Official Google org — published by googleworkspace on GitHub, not a third-party

No boilerplate — structured JSON output, works with jq and scripts

MCP-native — expose any Workspace API as an MCP tool with a single command

---