Google Workspace CLI (gws) — Connector Skill

Language

Detect from Personal Preferences. Respond in EN/HE/RU. AskUserQuestion if unknown.

---

What This Is

Google Workspace CLI (gws) — a unified command-line tool for Google Workspace (organizational) accounts. Provides CLI + MCP server for Gmail, Drive, Calendar, Sheets, Docs, Chat, Tasks, and 30+ more Google services. Built for humans and AI agents alike.

Key features:

• Dynamic API discovery — automatically reflects new Google API endpoints as they become available. No waiting for tool updates.
• MCP server built-in — first-class integration with Claude and other AI agents.
• Helper commands — shortcuts (prefixed with +) for common operations like sending email, checking agenda, uploading files.
• Full API access — every Google Workspace API method is callable directly.

GitHub: https://github.com/googleworkspace/cli

---

When to Use This vs google-personal

Skill	Use When
google-workspace (this skill)	Company/org Google accounts (@company.com, @org.edu, etc.)
google-personal	Personal Gmail accounts (@gmail.com)

If unsure which the user needs:

AskUserQuestion:

• "Work/organizational Google account (@company.com)"
• "Personal Gmail (@gmail.com)"

---

Installation

macOS (Homebrew)

brew install googleworkspace-cli

Windows / All Platforms (npm)

npm install -g @googleworkspace/cli

Alternative Methods

• Pre-built binaries: Download from https://github.com/googleworkspace/cli/releases
• From source: cargo install --git https://github.com/googleworkspace/cli --locked
• Nix: nix run github:googleworkspace/cli

Verify Installation

gws --version

---

Authentication Flow

Option A — Quick Setup (Recommended)

Requires gcloud CLI installed. This is the fastest path.

gws auth setup    # Interactive: creates Cloud project, enables APIs, handles login
gws auth login    # Select scopes for the services you need

AskUserQuestion after each command:

• "Done, continue"
• "I need help with this step"
• "Skip — I'll do this later"

Option B — Manual Setup (No gcloud)

Use this if gcloud is not installed or if the organization restricts gcloud.

Step 1: Go to https://console.cloud.google.com/apis/credentials

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Step 2: Create or select a Google Cloud project.

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Step 3: Enable the APIs you need. Go to API Library and enable each:

• Gmail API
• Google Calendar API
• Google Drive API
• Google Sheets API
• Google Docs API
• Google Tasks API
• (Enable others as needed: Chat, Slides, Admin SDK, etc.)

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Step 4: Create OAuth 2.0 Client ID:

• Go to Credentials > Create Credentials > OAuth client ID
• Application type: Desktop
• Download the credentials JSON file

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Step 5: Place the credentials file:

mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Step 6: Authenticate:

gws auth login

Follow the browser prompt to authorize. Select all scopes you need.

AskUserQuestion: ["Done, continue" / "I need help with this step" / "Skip — I'll do this later"]

Headless / CI Environments

For servers, containers, or CI pipelines where no browser is available:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

Use a service account JSON key or pre-authorized refresh token.

---

Verify Connection

Run these commands to confirm authentication is working:

gws gmail.users.messages.list --userId me --maxResults 3
gws calendar.events.list --calendarId primary --maxResults 3

If both return data, the connection is active and working.

---

MCP Server Mode (Recommended for Claude Cowork)

gws has a built-in MCP server. This is the best integration for Claude Cowork — all Google Workspace services become available as MCP tools automatically. No manual tool definitions needed.

Start the MCP Server

gws mcp

Add to Claude MCP Configuration

Add to .mcp.json in the project root, or via Claude Settings > MCP Servers:

{
  "mcpServers": {
    "google-workspace": {
      "command": "gws",
      "args": ["mcp"]
    }
  }
}

After adding the MCP configuration, restart Claude. All Google Workspace APIs are now available as tools — Gmail, Calendar, Drive, Sheets, Docs, Tasks, and every other enabled API.

The MCP server dynamically exposes all API methods. When Google adds new endpoints, they appear automatically after a gws update.

---

CLI Mode (Alternative to MCP)

If the user prefers CLI over MCP, or MCP is not available, gws commands can be called directly via Bash:

# List unread emails from today
gws --json gmail.users.messages.list --userId me --q "is:unread newer_than:1d"

# Send an email
gws +send --to user@example.com --subject "Hello" --body "Message content"

# Check calendar for next 3 days
gws +agenda --days 3

---

Helper Commands

Shortcuts prefixed with + for the most common operations:

Command	Description
gws +send	Send email
gws +reply	Reply to email
gws +triage	Email triage
gws +agenda	Calendar agenda
gws +insert	Create calendar event
gws +upload	Upload to Drive
gws +append	Append rows to Sheets
gws +read	Read Sheets data
gws +write	Write to Docs

Use gws +COMMAND --help for full options on any helper command.

---

Query Any API Schema

Not sure what parameters a method takes? Query its schema:

gws schema gmail.users.messages.list    # See parameters for any method
gws schema calendar.events.insert       # Calendar event creation params
gws schema drive.files.list             # Drive file listing params

This works for every Google API method — even ones not covered by helper commands.

---

Integration with Tandem Skills

After gws is set up and connected, existing Tandem workflow skills work automatically through MCP or CLI:

Tandem Skill	Google Integration
email-triage, email-draft, email-followup	Gmail MCP tools or gws +triage, gws +send
daily-briefing	gws +agenda or Calendar MCP
task-manager	Tasks MCP tools
budget-wizard	Export to Sheets via gws +append
presentation	Create in Slides via gws slides.presentations.create

Update CLAUDE.md After Connection

After successful setup, update ~/Tandem/CLAUDE.md Tools & Connectors section:

- Google Workspace (gws): Connected — Gmail, Calendar, Drive, Sheets, Docs, Tasks [MCP mode]

---

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Token expired or revoked	gws auth login to re-authenticate
403 Forbidden	Insufficient scopes	gws auth login and select additional scopes
API not enabled	API not turned on in Cloud Console	Enable the specific API at console.cloud.google.com/apis
MCP not connecting	gws not in PATH	Install globally or use full path in MCP config
redirect_uri_mismatch	Wrong OAuth client type	Recreate as Desktop application type
access_denied	Admin policy blocks app	Contact Google Workspace admin to allow the app
quota_exceeded	API rate limit hit	Wait and retry, or request quota increase in Cloud Console

Common Fixes

Re-authenticate with all scopes:

gws auth login --scopes gmail,calendar,drive,sheets,docs,tasks

Check current auth status:

gws auth status

Reset credentials and start fresh:

rm -rf ~/.config/gws/tokens
gws auth login

---

Security Notes

• Credentials stored encrypted in OS keyring or ~/.config/gws/
• Token auto-refresh — no manual renewal needed
• Supports Google Cloud Model Armor for prompt injection mitigation
• OAuth scopes are granular — only request what you need
• Tokens can be revoked at any time: gws auth revoke or via https://myaccount.google.com/permissions
• Not an officially supported Google product — community maintained, open source

---

Key Commands Reference

See references/gws-commands.md for the complete command reference organized by service, with exact syntax and common usage patterns.