Google Workspace -- Tool Router

Execution Mode

Detect which mode is available and use it.

MCP (preferred)

If MCP tools from the google-workspace server are available, call them directly. The tool names in the tables below are the base names -- prefix with the server name as needed (e.g. google-workspace:search_gmail_messages).

CLI (no MCP)

If no MCP tools are available, execute via bash:

uvx workspace-mcp --cli <tool_name> --args '{"user_google_email": "USER_EMAIL", ...}'

Before calling a tool, read the relevant reference file for exact parameter names and types. Only use parameters documented there -- do not invent parameters.

First-Time Setup

If a tool call fails with a credential error, walk the user through this setup.

1. Create OAuth credentials

Direct the user to Google Cloud Console:

• Create OAuth 2.0 Client ID (Desktop application type)
• Enable the Google APIs they need (Gmail, Drive, Calendar, etc.)
• Copy the Client ID and Client Secret

2. Store credentials

Direct the user to edit ~/.claude/settings.local.json themselves (this file is gitignored and never shared). Do not ask the user to paste secrets into the conversation. Tell them to add the following to the env block:

{
  "env": {
    "GOOGLE_OAUTH_CLIENT_ID": "their-client-id",
    "GOOGLE_OAUTH_CLIENT_SECRET": "their-secret"
  }
}

If settings.local.json already exists, they should merge into the existing env object, not replace it. These env vars are inherited by all MCP servers and CLI processes that Claude Code spawns.

3. Authenticate

• MCP mode: call start_google_auth to open the browser OAuth flow
• CLI mode: run any tool -- the first invocation opens the OAuth flow
• Credentials are cached in ~/.google_workspace_mcp/credentials (or as configured by WORKSPACE_MCP_CREDENTIALS_DIR) for future sessions

For server options, transport, auth modes, tool filtering, and deployment: references/server-options.md

Universal Patterns

• Consolidated "manage" tools use an action parameter for create/update/delete.

Tool Reference

Gmail

For parameters: references/gmail.md

Google Drive

For parameters: references/drive.md

Google Calendar

For parameters: references/calendar.md

Google Docs

For parameters: references/docs.md

Google Sheets

For parameters: references/sheets.md

Google Slides

For parameters: references/slides.md

Google Forms

For parameters: references/forms.md

Google Tasks

For parameters: references/tasks.md

Google Contacts

For parameters: references/contacts.md

Google Chat

For parameters: references/chat.md

Google Apps Script

For parameters: references/apps-script.md

Google Custom Search

For parameters: references/search.md

Auth

Parameters: user_google_email (string, optional), service_name (string, required -- e.g. "gmail", "drive"). Legacy OAuth 2.0 only -- disabled when OAuth 2.1 is enabled. In most cases, just call the tool you need and auth happens automatically.

Common Workflows

Reply to an email

1. search_gmail_messages -- find the email
2. get_gmail_message_content -- read it (get message_id and thread_id)
3. send_gmail_message -- reply using thread_id; omit reply headers to target the latest non-draft, non-trash message with an RFC Message-ID

Find and share a file

1. search_drive_files -- find the file
2. manage_drive_access -- share it
3. get_drive_shareable_link -- get the link

Read and update a spreadsheet

1. get_spreadsheet_info -- get sheet names
2. read_sheet_values -- read current data
3. modify_sheet_values -- write updated data
4. read_sheet_values -- verify the update

Create a formatted document

1. create_doc -- create the doc
2. modify_doc_text -- add text with formatting
3. insert_doc_elements -- add tables, lists, page breaks
4. update_paragraph_style -- apply heading styles
5. get_doc_as_markdown -- verify the result

Process email attachments

1. search_gmail_messages -- find the email
2. get_gmail_message_content -- get attachment metadata
3. get_gmail_attachment_content -- download the attachment

Edit a Google Doc

1. get_doc_as_markdown -- read current content
2. inspect_doc_structure -- find insertion points and indices
3. modify_doc_text / insert_doc_elements -- make changes
4. get_doc_as_markdown -- verify the result

Tips

• Check parameters: In CLI mode, run uvx workspace-mcp --cli <tool> --help for any unfamiliar tool.