Google Workspace — Shared Reference

MCP Tools

Tool	Description
google_sheets	Create spreadsheets, read/write cell data (auto-prepends sheets )
google_docs	Create documents, read/write text content (auto-prepends docs )
google_slides	Create presentations, read/write slides (auto-prepends slides )
google_gmail	Send, read, and manage Gmail messages
google_calendar	Create, list, and update Google Calendar events
request_google_file_picker	Request access to Google Drive files via the file picker UI

Scope & File Access

google_sheets, google_docs, and google_slides use the drive.file scope. They can only access:

1. Files created by this app (e.g., via spreadsheets create, documents create, presentations create)
2. Files explicitly selected by the user via Google Picker

To access an existing user file, call request_google_file_picker with the filename as query. The tool will:

• Search for already-accessible files matching that name
• If found, return file metadata directly (no pause, no picker)
• If not found, fall through to the Google Picker for the user to select the file

This means files picked in a previous task can be reused without showing the picker again.

Multi-Account Support

All tools accept an optional account parameter to target a specific connected Google account.

google_gmail(command: "list", account: "Work")
google_calendar(command: "list-events", account: "Personal")
request_google_file_picker(query: "Q3 Budget", account: "Work")

Account Routing Rules

Operation	When account omitted	When account specified
Read (list, search, get, free-time)	Queries all accounts	Queries only that account
Write (send, create, update, delete)	Ask which account first	Uses specified account

Specifying Accounts

Use either the label or the full email address:

google_gmail(command: "send ...", account: "Work")
google_gmail(command: "send ...", account: "alice@company.com")
request_google_file_picker(query: "Budget", account: "Personal")

Common Workflows

Create responses for google_docs, google_sheets, and google_slides always end with a direct link to the created Doc, Sheet, or Slide deck. Use that link in the task result when the user may want to open the file.

Sheets: Create, append rows, read back

# 1. Create a spreadsheet
google_sheets(command: "spreadsheets create --json '{\"properties\": {\"title\": \"Q3 Metrics\"}}'")

# 2. Add multiple rows with --json-values
google_sheets(command: "+append --spreadsheet '<spreadsheetId>' --json-values '[[\"Name\",\"Revenue\"],[\"Acme\",\"1.2M\"]]'")

# 3. Read back to verify
google_sheets(command: "+read --spreadsheet '<spreadsheetId>' --range 'Sheet1'")

Docs: Create, write text, read back

# 1. Create a document
google_docs(command: "documents create --json '{\"title\": \"Meeting Notes\"}'")

# 2. Append plain text
google_docs(command: "+write --document '<documentId>' --text 'Key decisions from today...'")

# 3. Read back to verify
google_docs(command: "documents get --params '{\"documentId\": \"<documentId>\"}'")

Slides: Create, get IDs, batchUpdate

# 1. Create a presentation
google_slides(command: "presentations create --json '{\"title\": \"Q3 Review\"}'")

# 2. Get the presentation to discover slide/placeholder IDs
google_slides(command: "presentations get --params '{\"presentationId\": \"<presentationId>\"}'")

IMPORTANT — --values vs --json-values (Sheets only)

• --values 'a,b,c' appends one row. It CANNOT be used multiple times to add more rows.
• --json-values '[["a","b"],["c","d"]]' appends multiple rows in a single call. Always use this for bulk data.

Error Handling

If a call fails, the tool returns an error message (not JSON). Check the message for HTTP status codes:

• 403 — Permission denied (file not in drive.file scope)
• 404 — File not found or not accessible
• 400 — Invalid request body or parameters

If a tool returns an error because no accounts are connected, direct the user to Settings → Integrations → Google Accounts.

If an account shows status expired, instruct the user to reconnect it in Settings → Integrations → Google Accounts.

Method Flags

Flag	Description
--params '{"key": "val"}'	URL/query parameters
--json '{"key": "val"}'	Request body
--page-all	Auto-paginate (NDJSON output)
--page-limit <N>	Max pages when using --page-all (default: 10)

--format json is automatically appended by the MCP server. Do not add it.

Security Rules

• Never output secrets (API keys, tokens) directly
• Always confirm with the user before executing write/delete commands
• Do NOT fall back to browser automation when MCP tools are available