Google Workspace CLI Opens Gmail and Drive to AI Agents
A Google DevRel engineer shipped a Rust-powered CLI that exposes all of Google Workspace to AI agents over MCP - with built-in prompt injection defense.
6 min read
A Google Workspace developer relations engineer quietly dropped a Rust-powered command-line tool on March 5 that gives AI agents direct, structured access to Gmail, Drive, Calendar, Sheets, Docs, Chat, and every other Workspace API - no custom integration code required. Five days later, it has more than 17,000 GitHub stars.
TL;DR
gwsis a CLI for all Google Workspace APIs, built in Rust and distributed via npm- A built-in MCP server lets any MCP-compatible AI client call Workspace APIs directly
- Commands are generated at runtime from Google's Discovery Service - no static command list
- Ships 67 pre-built agent skills and a
--sanitizeflag backed by Google Cloud Model Armor - Not officially supported by Google; expect breaking changes before v1.0
The tool is called gws, lives at github.com/googleworkspace/cli under Apache-2.0, and was authored by Justin Poehnelt, a DevRel engineer on Google's Workspace team. The repo explicitly states "This is not an officially supported Google product" - worth keeping in mind if you're building anything production-critical on top of it.
Installing and Getting Credentials
Getting the binary
npm install -g @googleworkspace/cli
That's the full install. The binary is pre-built Rust for Linux, macOS, and Windows. Node.js is required only as a distribution mechanism - the actual tool is native code.
Installing and verifying the gws CLI via npm.
Source: alphasignalai.substack.com
Authentication options
gws supports four auth paths:
| Method | Use case |
|---|---|
Interactive OAuth2 (gws auth setup) | Desktop use, human-in-the-loop |
Service account (--service-account ./key.json) | CI/CD pipelines, unattended agents |
| Application Default Credentials (ADC) | GCP-hosted environments |
Pre-obtained token (GOOGLE_WORKSPACE_CLI_TOKEN) | Short-lived scripting |
For agent workloads running headlessly, ADC or service accounts are the practical paths. The interactive OAuth flow requires gcloud CLI and works fine for local development but isn't usable for production automation.
How the API Surface Works
Dynamic command generation
This is the technical detail that makes gws different from other Workspace wrappers. Rather than shipping a hardcoded command set, the tool fetches Google's Discovery Service documents at runtime and builds its command surface on the fly. From the README: "gws doesn't ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its entire command surface dynamically."
Any new Workspace API method Google adds shows up without requiring a CLI update. The gws schema [method] command lets you inspect any API call's structure before running it. The --dry-run flag shows you exactly what HTTP request would be sent.
MCP integration
The tool originally shipped a dedicated gws mcp subcommand in v0.5.0, which ran a Model Context Protocol server over stdio and exposed selected Workspace APIs as structured tools. That subcommand was removed two days later in v0.8.0 - a real breaking change for anyone who had already built on it. The MCP functionality was reorganized in the v0.9.x releases.
As of the current version, four MCP clients have confirmed integrations: Claude Desktop (via config file), Gemini CLI (via gemini extensions install https://github.com/googleworkspace/cli), VS Code with the MCP extension, and Cursor through settings. Any client speaking MCP over stdio can connect.
The --tool-mode compact|full flag controls tool schema verbosity. compact works better for models with tighter context budgets.
The gws auth setup flow handling OAuth2 configuration for Workspace API access.
Source: alphasignalai.substack.com
Security Architecture
Prompt injection defense
Running AI agents against live Workspace data creates an obvious attack surface: a malicious document in Drive could instruct the agent to exfiltrate other documents. The --sanitize flag routes all API responses through Google Cloud Model Armor before they reach the AI.
gws drive files.list \
--sanitize "projects/MY_PROJECT/locations/global/templates/MY_TEMPLATE"
Model Armor applies malicious URI detection, responsible AI filters, and prompt injection classifiers. Two enforcement modes: warn (log the detection and continue) and block (halt the response). Both are configurable at the Google Cloud project level via gcloud.
This feature is in Preview status. It's a useful safety layer, not a guarantee.
Credential storage
Credentials are encrypted with AES-256-GCM and stored in the OS keyring. Version 0.9.1 fixed a bug where the encryption key was also written to a plaintext .encryption_key file - a reminder that the changelog deserves attention when upgrading a tool this new.
The Agent Skills Catalog
The repo ships 67 pre-built agent skills in four categories: 17 service skills covering the full Workspace surface (gws-drive, gws-gmail, gws-calendar), 21 helper skills for common tasks (gws-gmail-send, gws-calendar-agenda), 10 pre-built agent personas (persona-exec-assistant, persona-project-manager), and 19 workflow recipes (recipe-email-drive-link, recipe-reschedule-meeting).
Install them into any skills-compatible agent framework:
npx skills add github:googleworkspace/cli
If you're building agents on top of these, our guide to building your first AI agent covers the foundational setup worth getting right before adding Workspace data into the mix.
Where It Falls Short
The v1.0 disclaimer is real. Nine releases in four days, including the breaking removal of the MCP subcommand on day two, signals a tool being designed in public. Anyone building production workflows on the current API should track the changelog carefully.
OAuth apps in testing mode are capped at roughly 25 scopes. For a tool covering 50+ Workspace APIs, developers who want full surface access need to push their apps through Google's production verification process - which takes days and requires explicit approval.
The --sanitize flag requires a Google Cloud project and a configured Model Armor template. For simple scripting use cases, that's extra infrastructure. For anything touching sensitive user data in an agent context, it's not really optional.
There's also no official Google backing. Poehnelt built and shipped this as a DevRel project. Vercel CEO Guillermo Rauch called it "huge" on X the week it launched - "2026 is the year of Skills & CLIs" - which will drive adoption. But attention and support contracts are different things. The 17,000-star count means developers want this; whether Google formalizes it into an officially supported product determines how far those developers can take it.
For developers who were previously stitching together Workspace integrations with REST wrappers or webhook chains, gws cuts the setup work substantially. The open question isn't whether the tool works - the HN thread at 947 points and 290 comments suggests it does. The question is whether the MCP integration stabilizes before v1.0 so that agent pipelines built on it today don't break on the next release.
Sources:
