Google Workspace CLI (gws)

Google Workspace CLI (official Google release) for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every Workspace API. Includes native MCP server mod...

Security Scan

The skill's claimed purpose (official Google Workspace CLI) matches its instructions, but there are proportion and provenance inconsistencies — notably undeclared credential environment usage and no authoritative install provenance — that warrant caution before installing or granting access.

Purpose & Capability

Name, description, and required binary ('gws') align with the documented capabilities (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, MCP server). The operations and CLI flags shown in SKILL.md are consistent with a Workspace CLI.

Instruction Scope

SKILL.md stays on-purpose: it instructs installing gws, performing OAuth/service-account auth, and running gws mcp to expose Workspace APIs. It does allow broad access to user data (Gmail, Drive, etc.) when credentials are granted and instructs storing/using a credentials JSON file. The instructions do NOT ask the agent to read unrelated system files, but they do tell the user to place sensitive credential JSON on disk and set an env var to point at it.

Install Mechanism

There is no registry install spec, but SKILL.md recommends installing via npm (public registry), cargo (git), or nix. These are standard mechanisms (moderate risk). The registry metadata didn't include an automated install, and the package/source provenance in the registry is not fully authoritative (owner id unknown), so verify the npm package and GitHub repo are the official GoogleWorkspace org before installing.

Credentials

Registry metadata declares no required env vars, but SKILL.md references and recommends setting GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE and using a service-account JSON. The skill will require OAuth tokens or service-account keys (sensitive secrets) to function — these are not declared as required in metadata. Requesting Workspace credentials is expected for this CLI, but the omission in metadata and the broad scopes implied (Gmail/Drive/Calendar/etc.) increases risk if least-privilege practices are not followed.

Persistence & Privilege

always:false (default) so the skill is not force-included. Autonomous invocation is allowed (platform default). The SKILL.md shows how to run an MCP server that can expose hundreds of Workspace tools; while this is coherent with the skill purpose, it materially increases blast radius if the agent or skill is given credentials — limit the services (-s) and use compact mode where possible.

What to consider before installing

This skill appears to be the Workspace CLI described, but proceed cautiously: 1) Verify provenance — confirm the npm package @googleworkspace/cli and the GitHub repo are the official googleworkspace organization and check release signatures or commit history before installing. 2) Credentials — the CLI needs OAuth or a service-account JSON (sensitive). The SKILL.md references GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE but the registry metadata does not declare it; make sure you only provide least-privilege credentials and store them in a secure place (secret manager or isolated host). 3) Limit exposure — if you run gws mcp, restrict services with -s and use --tool-mode compact to reduce number of tools the agent can call. Prefer running the MCP server on an isolated machine or container rather than on a shared agent host. 4) Principle of least privilege — create service accounts with only the scopes needed, avoid granting broad Gmail/Drive scopes unless necessary, and rotate keys regularly. 5) Ask the publisher/maintainer for clarification: update registry metadata to declare required env vars (e.g., GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE), provide an authoritative install spec and checksums, and confirm that the package is the official Google release. If you cannot confirm provenance or cannot enforce least-privilege credentials and environment isolation, treat this skill as high-risk and avoid installing it in production environments.

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": "<base64>"}'

# 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