How to Use the GWS CLI to Connect Claude Code to Google Workspace

Why a CLI Beats MCP for Google Workspace Access

If you’ve tried connecting Claude Code to Google Workspace through an MCP server, you already know the friction. You need to configure a server, manage a persistent process, handle the MCP protocol layer, and debug connection issues before you’ve done anything useful. For many workflows, that overhead isn’t worth it.

The GWS CLI takes a different approach. Instead of running a server that Claude Code connects to, it’s a simple command-line tool that Claude Code calls directly using its bash execution capability. Read a spreadsheet, send an email, update a doc — it’s one shell command. No protocol, no server process, no extra configuration layer.

This guide walks through installing and configuring the GWS CLI, authenticating with Google, and putting it to practical use inside Claude Code sessions.

---

What the GWS CLI Actually Does

The GWS CLI is a lightweight command-line wrapper around Google’s core Workspace APIs. It exposes Google Sheets, Docs, Gmail, Drive, and Calendar as simple shell commands — the kind Claude Code can call directly with its Bash tool.

Because Claude Code can execute shell commands natively, any well-designed CLI becomes a tool. You don’t need to declare it, register it, or configure a tool schema. You just explain to Claude what command does what, and it figures out how to use it.

Here’s what that looks like in practice:

# Read a spreadsheet range
gws sheets read --id 1BxiM... --range "Sheet1!A1:C20"

# Append a row
gws sheets append --id 1BxiM... --range "Sheet1" --values "Alice,Sales,Q3"

# Get recent emails
gws gmail list --query "is:unread from:boss@company.com" --limit 5

# Create a new doc
gws docs create --title "Weekly Report" --content "# Summary..."

# Upload a file to Drive
gws drive upload --file ./report.pdf --folder "1ABC..."

Each command outputs clean JSON or plain text, which Claude Code can parse and act on. The design is intentional — it’s built to be readable by an LLM.

---

Prerequisites

Before installing the GWS CLI, make sure you have the following in place.

On your machine:

• Node.js 18+ or Python 3.9+ (depending on which version of the CLI you install)
• Claude Code installed and running
• A terminal with standard shell access

On Google’s side:

• A Google Cloud project (free to create at console.cloud.google.com)
• The relevant APIs enabled for your project: Sheets API, Docs API, Gmail API, Drive API
• OAuth 2.0 credentials configured as a Desktop application

You’ll also need to be comfortable running a one-time OAuth flow in your browser to grant the CLI access to your Google account. This only happens once.

---

Step 1: Install the GWS CLI

The most common installation path uses npm:

npm install -g @gws/cli

If you prefer Python:

pip install gws-cli

After installation, verify it works:

gws --version

You should see a version number printed. If you get a “command not found” error, make sure your global npm bin directory is on your PATH.

---

Step 2: Set Up a Google Cloud Project

This is the part most tutorials rush through. Take five minutes to do it right — it’ll save you hours of auth debugging later.

Create the Project

1. Go to Google Cloud Console
2. Click New Project in the top navigation
3. Give it a name like gws-cli-local and click Create

Enable the APIs You Need

In the left sidebar, go to APIs & Services → Library. Search for and enable each of the following:

• Google Sheets API
• Google Docs API
• Gmail API
• Google Drive API

You only need to enable the ones you’ll actually use. If you’re just working with Sheets and Drive, skip Gmail and Docs for now.

Configure the OAuth Consent Screen

Navigate to APIs & Services → OAuth consent screen.

• Select External (unless you’re on Google Workspace and want to restrict to your org)
• Fill in the required fields: app name, support email, developer email
• On the Scopes step, you can skip for now — the CLI will request scopes when you authenticate
• Add your own Google account as a test user

Create OAuth Credentials

Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

• Application type: Desktop app
• Name it something like gws-cli-credentials
• Click Create

Download the JSON file. This is your credentials.json. Keep it somewhere safe — you’ll reference its path during CLI setup.

---

Step 3: Authenticate the CLI

Run the authentication command, passing the path to your credentials file:

gws auth --credentials /path/to/credentials.json

This opens a browser window with Google’s OAuth consent screen. Log in, grant the requested permissions, and you’ll be redirected to a localhost callback URL. The CLI captures the token and stores it locally (usually in ~/.config/gws/tokens.json).

You only need to do this once. The CLI handles token refresh automatically after that.

To verify authentication worked:

gws auth status

You should see your authenticated Google account email printed back.

---

Step 4: Test Basic Commands

Before bringing Claude Code into the picture, confirm the CLI works on its own.

Test Sheets Access

Grab the ID of any Google Sheet you own — it’s the long string in the URL between /d/ and /edit. Then run:

gws sheets read --id YOUR_SHEET_ID --range "Sheet1!A1:D5"

You should see JSON output with the cell values.

Test Gmail

gws gmail list --query "is:unread" --limit 3

This returns your three most recent unread emails as structured JSON.

Test Drive

gws drive list --folder root --limit 10

Lists 10 items in your Drive root.

If any of these fail with a permissions error, double-check that the corresponding API is enabled in your Cloud project.

---

Step 5: Use GWS CLI Inside Claude Code

Now the useful part. Claude Code can call any bash command — so all you need is a clear system prompt or initial instruction telling it what tools are available.

Option A: Add a CLAUDE.md File

The cleanest approach is creating a CLAUDE.md file in your project root. Claude Code reads this automatically at the start of every session.

## Available Tools

You have access to the GWS CLI for Google Workspace operations.

### Sheets
- Read: `gws sheets read --id <id> --range <range>`
- Append: `gws sheets append --id <id> --range <range> --values "v1,v2,v3"`
- Update: `gws sheets update --id <id> --range <range> --values "v1,v2,v3"`

### Gmail
- List: `gws gmail list --query <query> --limit <n>`
- Read: `gws gmail read --id <message_id>`
- Send: `gws gmail send --to <email> --subject <subject> --body <body>`

### Docs
- Create: `gws docs create --title <title> --content <text>`
- Read: `gws docs read --id <doc_id>`
- Append: `gws docs append --id <doc_id> --content <text>`

### Drive
- List: `gws drive list --folder <folder_id> --limit <n>`
- Upload: `gws drive upload --file <path> --folder <folder_id>`
- Download: `gws drive download --id <file_id> --output <path>`

All commands output JSON unless --format plain is specified.
Sheet IDs and Doc IDs come from the URL of the respective file.

Option B: Describe Tools in Your First Message

If you don’t want a CLAUDE.md file, just describe what’s available at the start of your session:

“You have access to a GWS CLI. You can run gws sheets read --id X --range Y to read spreadsheet data, gws gmail list --query Z to get emails, and so on. Use bash to call these commands when I ask you to work with Google Workspace.”

Claude Code is good at inferring flag structures from examples. You don’t need to document every flag.

---

Step 6: Real-World Use Cases

Here’s what this setup actually enables.

Automated Report Generation

Ask Claude Code to pull data from a spreadsheet, analyze it, and write a summary doc:

“Read the sales data from Sheet1 of spreadsheet [ID], calculate total revenue by region, and create a new Google Doc titled ‘Q3 Revenue Summary’ with a plain-text breakdown.”

Claude Code will run the gws sheets read command, process the JSON output, compute the totals, then call gws docs create with the formatted output.

Email Triage and Response Drafts

“Check my last 10 unread emails from client@company.com and draft a reply to any that mention the project deadline.”

Claude reads the emails via gws gmail list and gws gmail read, identifies relevant threads, and drafts responses — which you review before sending.

Spreadsheet Maintenance

“Look at the ‘Tasks’ sheet in [ID]. For any row where the Status column says ‘Complete’, move it to the ‘Archive’ sheet and delete the original row.”

This kind of conditional read-modify-write operation would take a custom script to automate. Claude Code handles the logic; the GWS CLI handles the API calls.

Drive File Organization

“List everything in my ‘Inbox’ Drive folder. Move PDF files to the ‘Contracts’ folder and image files to ‘Assets’.”

Claude reads the directory listing, filters by file type from the metadata, and issues the appropriate gws drive move commands.

---

Troubleshooting Common Issues

”insufficient authentication scopes”

This means the OAuth token was issued without the permission the command needs. Re-run gws auth --credentials /path/to/credentials.json and make sure to approve all requested scopes during the browser flow.

”API not enabled for project”

You’ve called an endpoint for an API you didn’t enable. Go back to Google Cloud Console → APIs & Services → Library and enable the relevant API. Changes propagate within a minute or two.

Token expired or revoked

Run gws auth status to check. If it shows expired, run gws auth refresh. If it shows invalid, you need to re-run the full auth flow.

Claude Code runs the command but gets malformed JSON

Add --format json explicitly to the command. Some versions of the CLI default to plain text in certain modes.

Rate limit errors

Google’s free tier has per-minute quotas for each API. If you’re hitting them, add a short sleep 1 between rapid successive calls, or request a quota increase in Google Cloud Console.

Claude Code won’t execute the bash command

Make sure you’re running Claude Code with bash tool access enabled. If you’ve restricted tool use, bash may be disabled. Check your Claude Code configuration.

---

Going Further: Combining GWS CLI With Automation Workflows

The GWS CLI plus Claude Code is a strong setup for interactive, one-off tasks. But if you want to run Google Workspace automations on a schedule — or build workflows that non-developers can trigger — you need something that runs without a human in the loop.

That’s where MindStudio fits in. MindStudio is a no-code platform for building AI agents and automated workflows, with native Google Workspace integrations built in. You can connect to Sheets, Docs, Gmail, and Drive without writing any code or managing CLI credentials.

Where the GWS CLI approach is great for developers doing exploratory work inside a Claude Code session, MindStudio handles the persistent, scheduled, and shared workflow use cases:

• A daily agent that reads new rows from a spreadsheet and sends status emails
• A workflow triggered by a new Drive file upload that processes the document and logs results to Sheets
• A shared agent your whole team can use to query Workspace data without needing CLI access

MindStudio supports Claude alongside 200+ other AI models, so you can use the same reasoning capabilities inside a fully automated workflow. You can try it free at mindstudio.ai.

---

Frequently Asked Questions

Does the GWS CLI work with Google Workspace for Organizations (formerly G Suite)?

Yes, but there’s an extra step. For organizational accounts, you may need an admin to approve the OAuth app in the Google Workspace Admin Console under Security → API Controls → App access control. Once approved, authentication works the same way as with personal accounts.

Is this approach secure? Where are my OAuth tokens stored?

Tokens are stored locally in your user config directory (usually ~/.config/gws/). They never leave your machine. The CLI uses standard OAuth 2.0 refresh token flow — the same mechanism used by official Google tools. Don’t commit the tokens.json file to version control.

How is this different from using Google’s MCP server for Claude?

Google has an experimental MCP server for Workspace. It works, but it requires running a persistent process, managing an MCP connection, and handling the protocol layer. The GWS CLI is simpler: it’s a stateless CLI that Claude Code calls with bash. No server to run, no connection to maintain. For most use cases, the CLI approach is faster to set up and easier to debug.

Can I use the GWS CLI with other AI agents, not just Claude Code?

Yes. Any agent that can execute shell commands can use the GWS CLI. That includes LangChain agents with bash tools, CrewAI agents, custom Python agents with subprocess, and others. The CLI is model-agnostic.

What are the API rate limits I should know about?

Google’s free-tier limits vary by API. For Sheets, the limit is 300 read requests per minute per project. Gmail allows 250 quota units per user per second, where most operations cost 5–10 units. Drive has a general limit of 1,000 requests per 100 seconds. For most interactive Claude Code workflows, you won’t hit these. If you’re running batch operations, add delays between calls.

Can I grant the CLI access to someone else’s Google account?

Only if they go through the OAuth flow themselves. The CLI can’t be pre-authenticated for another user’s account without them interacting with the consent screen. If you need shared access, look at service accounts (for Drive and Sheets) or domain-wide delegation (for Workspace orgs).

---

Key Takeaways

• The GWS CLI gives Claude Code read/write access to Google Sheets, Docs, Gmail, and Drive via simple bash commands — no MCP server required.
• Setup involves three things: installing the CLI, creating a Google Cloud project with the right APIs enabled, and running a one-time OAuth flow.
• A CLAUDE.md file in your project root is the cleanest way to tell Claude Code what commands are available.
• Common issues (scope errors, expired tokens, rate limits) all have straightforward fixes once you know what to look for.
• For persistent, scheduled, or team-shared workflows, MindStudio’s native Google Workspace integrations extend what you can do without adding more CLI complexity.