Google Workspace CLI (official Google release) for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every Workspace API. Includes native MCP server mod...
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.
npm install -g @googleworkspace/cli
# or: cargo install --git https://github.com/googleworkspace/cli --locked
# or: nix run github:googleworkspace/cli
Verify:
gws --version
⚠️ Auth requires manual action — OAuth credentials must be set up once per account.
gws auth setup # creates GCP project, enables APIs, logs in
gws auth login # subsequent logins / scope changes
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.jsongws auth loginexport GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
Credentials are encrypted at rest (AES-256-GCM) with OS keyring.
# 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
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
{
"mcpServers": {
"google-workspace": {
"command": "gws",
"args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs", "--tool-mode", "compact"]
}
}
}
After auth setup, the agent can:
Example — list recent emails:
gws gmail users messages list --params '{"userId": "me", "maxResults": 10, "q": "is:unread"}'
gws auth setup before first usegoogleworkspace on GitHub, not a third-partyjq and scriptsgws auth setup required (GCP project needed)ZIP package — ready to use