How to Use the Google Workspace CLI to Give AI Agents Full Access to Drive, Docs, and Sheets

Why Your AI Agent Can’t Use Google Docs Properly (Yet)

Ask an AI agent to “create a report in Google Docs” and you’ll almost certainly get one of two things: a markdown file saved locally, or a blank document with all the content dumped as unformatted plain text. Neither is what you actually wanted.

The Google Workspace CLI changes this. It’s an open-source command-line interface that gives AI agents like Claude Code a structured, authenticated way to interact with Google Drive, Docs, and Sheets — creating properly formatted documents, reading file contents, managing spreadsheet data — without the agent needing to know anything about REST endpoints, OAuth flows, or API request bodies.

This guide covers what the CLI is, how to set it up, and how to wire it into Claude Code so your agent can work with Workspace files the way a human would.

The Real Problem: Why AI Agents Fail at Google Workspace

Before getting into the setup, it’s worth understanding why this problem exists in the first place.

Markdown Is Not a Google Doc

When you ask an AI to write something, the natural output is markdown. That’s how language models structure formatted text. But Google Docs doesn’t accept markdown. A Google Doc is built on a structured document model with paragraphs, headings, tables, inline styles, and named styles — none of which maps directly to markdown syntax.

If you paste markdown into a Google Doc, you get asterisks and hashtags, not bold text and headings. Agents that try to create Docs by writing content to a file and uploading it end up with unformatted blobs.

Raw API Calls Are Unreliable

The Google Docs API lets you create properly formatted documents programmatically, but it requires batched requests with specific JSON structures. A batchUpdate call to insert styled text looks nothing like “write this heading.” The API is powerful but verbose.

Agents that try to interact with Workspace APIs directly often fail because:

The request structure is complex and changes per operation
Authentication tokens expire and need refreshing
Error handling requires understanding specific Google API error codes
Scopes need to be configured correctly for read vs. write operations

Even experienced developers make mistakes here. Agents make more.

Authentication Is a Standalone Problem

Google’s OAuth2 flow involves browser redirects, consent screens, token storage, and refresh logic. An AI agent running in a terminal has no browser. Wiring this up manually every time is impractical, and exposing service account credentials in an agent’s context is a security risk.

The Google Workspace CLI handles all of this. It abstracts the API calls into readable commands and handles auth separately from the agent’s execution context.

What the Google Workspace CLI Is

The Google Workspace CLI is an open-source tool designed to give AI agents and automation scripts a clean interface to Google Workspace services. Rather than requiring raw API knowledge, it exposes human-readable commands that translate into the appropriate API calls behind the scenes.

It’s built on top of Google’s official client libraries and designed specifically with agent use in mind — meaning it works well as an MCP (Model Context Protocol) server, which is how Claude Code and similar agent frameworks discover and use external tools.

What It Covers

The CLI provides structured access to:

Google Drive — list files, search by name or type, read file contents, upload files, create folders, move and copy items
Google Docs — create new documents with proper heading styles, append content, read document structure and text, apply formatting
Google Sheets — read cell ranges, write values, append rows, clear ranges, create new sheets, manage named ranges

Each of these operations is exposed as a named tool with typed inputs and outputs. Claude Code sees them as capabilities it can call directly, like drive_list_files or docs_create_document.

How It’s Different from Direct API Access

The key difference is abstraction. When Claude Code calls docs_create_document with a title and a structured content block, the CLI handles:

Converting the content into the correct batchUpdate request format
Managing the OAuth token lifecycle
Retrying on transient errors
Returning a clean response with the document URL and ID

The agent gets back what it needs. It doesn’t need to know that creating a heading in Google Docs requires a createParagraph request followed by an updateParagraphStyle request with a namedStyleType of HEADING_1.

Setting Up the Google Workspace CLI

This section walks through the full setup process from a fresh state. The steps assume you’re on macOS or Linux. Windows users can follow the same steps in WSL.

Prerequisites

Before you start, you need:

Node.js 18 or higher installed
A Google account with access to the Workspace services you want to use
Access to the Google Cloud Console (free with any Google account)
Claude Code installed and configured

Step 1: Create a Google Cloud Project

Go to console.cloud.google.com and create a new project. Give it a descriptive name like workspace-agent-cli. This project will hold the credentials your CLI uses to authenticate with Google’s APIs.

Once the project is created:

Navigate to APIs & Services → Library
Enable the following APIs:
- Google Drive API
- Google Docs API
- Google Sheets API
Wait for each to enable before proceeding

Navigate to APIs & Services → OAuth consent screen.

Choose External if you’re setting this up for personal use, or Internal if you’re inside a Google Workspace organization
Fill in the required fields: app name, user support email, developer contact email
Add the following scopes:
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/documents
- https://www.googleapis.com/auth/spreadsheets

If you selected External, add your own email address as a test user. This allows you to authenticate without publishing the app.

Step 3: Create OAuth Credentials

Navigate to APIs & Services → Credentials → Create Credentials → OAuth Client ID.

Application type: Desktop app
Give it a name like workspace-cli-desktop
Click Create

Download the resulting JSON file. It contains your client_id and client_secret. Save it somewhere accessible — you’ll reference it during CLI configuration.

Step 4: Install the CLI

Clone the repository and install dependencies:

git clone https://github.com/google-workspace/workspace-cli
cd workspace-cli
npm install

If there’s a global install option available:

npm install -g @google/workspace-cli

Check the installation:

workspace-cli --version

Step 5: Authenticate

Run the authentication command and pass the path to your credentials file:

workspace-cli auth login --credentials ~/path/to/credentials.json

This will open a browser window with Google’s consent screen. Sign in with the account you want the agent to act on behalf of, grant the requested permissions, and the CLI will save a token locally for future use.

Tokens are stored in ~/.workspace-cli/token.json by default. The CLI handles refresh automatically when tokens expire.

Verify authentication worked:

workspace-cli drive list --limit 5

If you see a list of files from your Drive, you’re authenticated and ready to proceed.

Connecting the CLI to Claude Code

Claude Code uses the Model Context Protocol (MCP) to discover and call external tools. The Google Workspace CLI exposes itself as an MCP server, which means Claude Code can use its capabilities as native tools — no manual command construction required.

What MCP Means in Practice

MCP is a standard protocol for exposing tools to AI agents. When Claude Code starts, it can connect to one or more MCP servers. Each server advertises a list of tools with names, descriptions, and typed input schemas. Claude Code reads these and uses them when appropriate.

From Claude Code’s perspective, calling drive_search_files works the same way as any built-in capability. It describes what it wants to do, passes the right parameters, and gets a structured response back.

Configuring Claude Code to Use the CLI

Claude Code reads MCP server configurations from a config file. Open or create ~/.claude/claude_desktop_config.json (on macOS) or the equivalent for your platform:

{
  "mcpServers": {
    "google-workspace": {
      "command": "workspace-cli",
      "args": ["mcp-server"],
      "env": {
        "WORKSPACE_CREDENTIALS": "/path/to/credentials.json",
        "WORKSPACE_TOKEN": "/path/to/token.json"
      }
    }
  }
}

Adjust the paths to match where you saved your credentials and where the CLI stored the token after authentication.

If you installed the CLI globally, workspace-cli will be found automatically. If you installed it locally, use the full path to the binary.

Restart Claude Code after saving the config file.

Verifying the Connection

In a Claude Code session, ask it to list your Drive files:

“List the 5 most recent files in my Google Drive”

If everything is configured correctly, Claude Code will use the drive_list_files tool, fetch the results, and display them. If you see an error, check that:

The CLI is accessible from the path you specified
The credential and token paths are correct
The OAuth scopes include Drive access

Working with Google Drive

With the CLI connected, Claude Code has full read and write access to Drive. Here’s what that looks like in practice.

Listing and Searching Files

Claude Code can list files by folder, search by name, or filter by file type. Internally, the CLI translates these into Drive API queries using the q parameter syntax, so you don’t have to.

Example prompts that work:

“Show me all spreadsheets in my Drive”
“Find files named ‘Q3 Report’”
“List everything in the folder called ‘Marketing Assets’”

The CLI handles folder ID resolution automatically. You reference folders by name; the CLI figures out the ID.

Reading File Contents

For Google-native files (Docs, Sheets, Slides), the CLI exports content in a readable format. For Docs, it returns structured text. For Sheets, it returns a 2D array of cell values. For uploaded files like PDFs or images, it returns metadata and (where applicable) extracted text.

This is useful for agents that need to read existing content before making decisions — summarizing a report, checking a spreadsheet for specific values, or reading a brief before writing something new.

Uploading and Creating Files

The CLI can:

Upload local files to Drive with a specified name and parent folder
Create new Google-native files (Docs, Sheets) from scratch
Create folder structures programmatically

When creating files programmatically, the CLI returns the file ID and shareable URL, which Claude Code can pass along or use in subsequent operations.

Managing File Permissions

You can grant view or edit access to specific users or make files accessible to anyone with the link. This is useful for agents that create reports and need to share them with a team automatically.

workspace-cli drive share --file-id FILE_ID --email user@example.com --role writer

Claude Code can do this as part of a workflow: create a doc, populate it, share it with a specific person.

Creating and Managing Google Docs

This is where the CLI’s value is clearest. Getting properly formatted Google Docs out of an AI agent without this tool is genuinely difficult.

Creating a New Document

When Claude Code creates a document using the CLI, it doesn’t just dump text into a blank file. It structures the content using Google’s document model — proper headings, paragraphs, bold/italic inline styles, and lists.

A typical agent workflow:

Claude generates the content in structured form (title, sections, body text)
The CLI converts this into the appropriate API calls
A properly formatted Google Doc is created with correct heading hierarchy

The resulting document looks like something a human wrote in Docs — not like pasted text.

Supported Formatting Elements

The CLI handles:

Headings (H1 through H6) using Google’s named styles
Paragraph text with inline bold, italic, underline, and strikethrough
Bulleted and numbered lists with proper list nesting
Tables with specified rows and columns
Horizontal rules
Hyperlinks embedded in text runs

Appending Content to Existing Documents

If a document already exists, Claude Code can append new sections without overwriting existing content. This is useful for:

Adding a summary section to a report that was already drafted
Appending meeting notes to an ongoing log document
Adding a new entry to a document that serves as a running record

The CLI handles cursor positioning automatically — new content goes at the end of the document body, before the final newline.

Reading Document Structure

Claude Code can read an existing Google Doc and get back its full content as structured data. This includes the text of each paragraph, the style applied to each (heading level, body text, etc.), and any inline formatting.

This is useful when an agent needs to understand an existing document before editing it — for example, checking if a specific section already exists before adding it.

Managing Google Sheets

Sheets is the service agents most commonly need for data workflows. The CLI gives Claude Code clean read and write access without needing to construct complex range requests.

Reading Data from a Sheet

You can read a single cell, a named range, or an entire sheet. The CLI returns values as a clean 2D array.

Example agent task: “Read the ‘Budget’ sheet and tell me which rows have expenses over $10,000.”

Claude Code calls sheets_read_range, gets back the cell data, processes it, and responds — no raw API knowledge needed.

Writing Values to a Sheet

Writing works the same way in reverse. You specify the range and provide the values, and the CLI handles the update.

Common use cases for agent-driven writes:

Logging results to a tracking sheet at the end of a workflow
Updating a status column based on some automated check
Filling in a template sheet with values from another source

The CLI uses valueInputOption: USER_ENTERED by default, which means values are interpreted the same way Google Sheets would interpret manual input — formulas evaluate correctly, dates format properly.

Appending Rows

For logging or data collection workflows, appending rows (rather than writing to a specific range) is more reliable. The CLI handles finding the first empty row automatically.

workspace-cli sheets append --spreadsheet-id SPREADSHEET_ID --sheet "Sheet1" --values "[['2025-01-15', 'Completed', '$4,200']]"

From Claude Code’s perspective: “Append the results of this run to the ‘Log’ sheet in the reporting spreadsheet.”

Creating New Sheets and Spreadsheets

The CLI can create a new spreadsheet from scratch, or add a new sheet tab to an existing spreadsheet. When creating from scratch, you can specify the sheet name, initial column headers, and basic formatting.

This is useful for agents that generate periodic reports — each run creates a new sheet named with the date, populates it with data, and shares the link.

Working with Formulas

When appending or writing data, the CLI supports formula strings. Values starting with = are treated as formulas. This means an agent can populate a template that has formula cells without breaking them — it just leaves those cells alone or writes adjacent data that feeds into the formulas.

Practical Agent Workflows Built on the CLI

Seeing the pieces separately is useful, but the real value comes from combining them. Here are a few complete workflows that become straightforward once the CLI is in place.

Weekly Report Generation

An agent workflow that:

Reads raw data from a Google Sheet (sales numbers, completion rates, whatever the source is)
Calculates summaries and identifies notable items
Creates a new Google Doc with a formatted report — proper headings, a summary section, a data table, and bullet-point insights
Shares the doc with the relevant team members via Drive permissions

This used to require custom code connecting multiple APIs. With the CLI, it’s a Claude Code workflow where each step is a tool call.

Content Approval Tracker

An agent that monitors a Sheet used as a content calendar:

Reads all rows where the “Status” column says “Ready for Review”
For each item, reads the linked Google Doc containing the draft
Summarizes the content and adds a summary note to the Sheet
Updates the status column to “Reviewed” with a timestamp

Document Templating

An agent that fills in a standard document template:

Makes a copy of a template Doc in Drive
Reads client-specific data from a Sheet
Fills in placeholders throughout the document with the actual values
Stores the completed document in the client’s folder
Shares the document with the client’s email

This kind of workflow previously required Apps Script or custom Python. Now it’s within reach of any agent with the CLI available.

Scoping and Security Considerations

Giving an AI agent access to your Google Drive is not something to set up carelessly. A few practices that reduce risk.

Use Minimum Required Scopes

Don’t grant the drive scope (full Drive access) if your use case only needs to read files. The available scopes, from most to least permissive:

drive — full read/write access to all files
drive.file — access only to files the app created
drive.readonly — read-only access to all files
documents — access to Google Docs files
spreadsheets — access to Google Sheets files

If your agent only creates and reads Docs, use documents instead of drive. If it only reads Sheets, use spreadsheets.readonly.

Separate Credentials per Agent or Use Case

Don’t share OAuth credentials between agents that do different things. Create separate Google Cloud projects (or at minimum separate OAuth clients) for each distinct use case. This makes it easier to revoke access selectively and track which agent is doing what.

Store Tokens Securely

The token file stored by the CLI after authentication contains your access and refresh tokens. Treat this like a password file. Don’t commit it to version control, don’t include it in Docker images, and set appropriate file permissions:

chmod 600 ~/.workspace-cli/token.json

Audit What the Agent Does

The Drive API logs can be reviewed in the Google Cloud Console under Logging. For sensitive workflows, enable audit logging and periodically review what your agent is reading and modifying.

Troubleshooting Common Issues

”Insufficient Permission” Errors

This usually means the OAuth scope doesn’t cover the operation you’re trying to perform. Check the scopes you configured during the consent screen setup and make sure they match what the CLI is trying to do. You may need to re-authenticate after updating scopes:

workspace-cli auth logout
workspace-cli auth login --credentials ~/path/to/credentials.json

“File Not Found” When the File Exists

Drive API queries are case-sensitive and exact-match by default. If you’re searching for a file by name, make sure the name matches exactly. The CLI’s search uses Drive’s fullText contains query for keyword searches and name = 'exact name' for exact matches.

Also check that the authenticated account has access to the file. If someone else owns it and hasn’t shared it with you, it won’t appear in search results.

Claude Code Doesn’t See the Workspace Tools

If Claude Code isn’t offering Workspace tools in its responses, verify:

The MCP config file is saved in the right location
The command path points to the actual CLI binary (try which workspace-cli to confirm)
Claude Code was restarted after the config file was updated
The MCP server starts without errors (run workspace-cli mcp-server directly to check)

Rate Limiting

Google’s APIs have per-minute and per-day quotas. If you’re running high-volume workflows, you may hit rate limits. The CLI includes basic exponential backoff, but for heavy use you may need to request quota increases in the Google Cloud Console under APIs & Services → Quotas.

Where MindStudio Fits for Teams Who Want This Without the Setup

The Google Workspace CLI is the right tool if you’re running Claude Code locally and comfortable with OAuth setup and config files. But for teams building agents that need Workspace access without any of that infrastructure work, MindStudio is worth looking at.

MindStudio includes pre-built integrations with Google Drive, Docs, and Sheets as part of its 1,000+ connector library. You can build an agent workflow that reads from a spreadsheet, generates a formatted document, and shares it — using a visual builder, without writing API configuration or managing credentials.

The Workspace integrations in MindStudio handle authentication through a simple OAuth connect flow inside the platform, and the tools are available as drag-and-drop actions in any workflow. You get the same capabilities as the CLI — structured Docs creation, Drive file management, Sheets read/write — but the setup takes minutes instead of an afternoon.

For developers who are building agents that other people in their organization need to use, MindStudio is particularly useful. You build the agent once, publish it, and your teammates use it through a clean UI without needing to configure anything themselves.

You can try MindStudio free at mindstudio.ai.

Frequently Asked Questions

What is the Google Workspace CLI and how does it differ from the Google Cloud SDK?

The Google Cloud SDK (gcloud) is a general-purpose CLI for Google Cloud infrastructure — compute instances, storage buckets, IAM policies. The Google Workspace CLI is specifically focused on Workspace applications: Drive, Docs, Sheets, Gmail, Calendar. It wraps the Workspace-specific APIs in commands designed for use by AI agents and automation scripts, including MCP server mode for direct integration with tools like Claude Code.

Does the Google Workspace CLI work with other AI agents besides Claude Code?

Yes. Because it exposes an MCP server interface, it works with any AI agent framework that supports MCP — including tools like Cursor, Windsurf, and custom agents built with LangChain or LlamaIndex that have MCP client support. The setup differs slightly depending on how each framework handles MCP configuration, but the underlying tools are the same.

Can the CLI access Google Workspace accounts that my organization controls, or only personal accounts?

It works with both. For organizational accounts (Google Workspace Business or Enterprise), you’ll need to configure the OAuth app as an internal app in your organization’s Google Workspace Admin Console, or have your IT administrator approve the app for use. For personal Gmail/Drive accounts, setup is straightforward via the standard external OAuth flow with test user configuration.

What happens when the OAuth token expires?

The CLI handles token refresh automatically. OAuth access tokens typically expire after one hour, but the CLI uses the stored refresh token to request a new access token without requiring user interaction. As long as the refresh token remains valid (it stays valid unless you revoke access or remain inactive for an extended period), the CLI continues to work without re-authentication.

Is it safe to give Claude Code access to my entire Google Drive?

That depends on the sensitivity of what’s in your Drive and how much you trust the workflows you’re building. For most use cases, it’s safer to scope the credentials to specific folders or to use the drive.file scope, which only allows access to files the agent itself created. Review the scopes you configure and apply the principle of least privilege — grant only what the specific workflow actually needs.

Can the CLI create Google Slides presentations?

The current focus is Drive, Docs, and Sheets. Google Slides support is technically possible using the Slides API, but it’s not always included in the initial scope of these CLIs. Check the project’s documentation and GitHub issues for the current state of Slides support. As an alternative, agents can create Docs-based presentations or output structured content that can be manually imported into Slides.

How does this handle large files or documents?

The Google Docs API has a limit on the size of a single batchUpdate request. For very large documents, the CLI breaks content into multiple batched requests. For large files in Drive (like video files), the CLI uses resumable uploads automatically. Sheet operations that involve many rows are handled in chunks to stay within the API’s rate limits.

Key Takeaways

Getting AI agents to work with Google Workspace properly has been harder than it should be. The Google Workspace CLI solves the core problems: authentication complexity, raw API verbosity, and the formatting gap between how agents produce text and how Google Docs expects it.

Here’s what to remember:

The CLI acts as a translation layer between Claude Code’s tool calls and Google’s APIs — you don’t need to know how the Docs batchUpdate API works to create a properly formatted document.
Setup involves four main steps: create a Google Cloud project, enable the relevant APIs, configure OAuth credentials, and connect the CLI to Claude Code via MCP.
Scope your credentials carefully — use the minimum permissions needed for your workflow, and store tokens securely.
The same tools work across agents — any MCP-compatible agent framework can use the CLI, not just Claude Code.
For teams who need Workspace integrations without CLI setup, MindStudio’s no-code platform includes pre-built Google Workspace connectors that work immediately after an OAuth connect step.

The combination of a capable AI coding agent and clean programmatic access to Workspace is powerful. Reports get written and formatted. Spreadsheets get updated. Files get organized. The plumbing is handled — the agent can focus on the actual work.

If you want to go further with building agents that connect to business tools without managing infrastructure, MindStudio is worth exploring. It’s free to start, and the Workspace integrations are ready to use from day one.