/managing-google-workspace

name: managing-google-workspace
description: >
  Manages Google Workspace operations across 12 services (Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script, Custom Search).
  Supports MCP tools or CLI via uvx workspace-mcp --cli. Provides tool routing, workflows, and parameter guidance for 114 tools.
  Triggers for "check my email", "find a file", "schedule a meeting", "update the spreadsheet", "share a doc",
  "create a presentation", "add a task", "look up a contact", or any mention of Google Workspace services.
allowed-tools: Bash(uvx workspace-mcp *)
user-invocable: false

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](https://console.cloud.google.com/apis/credentials):

• 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](references/server-options.md)

Universal Patterns

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

Tool Reference

Gmail

| Task | Tool | |------|------| | Search/find emails | `search_gmail_messages` | | Read one email | `get_gmail_message_content` | | Read multiple emails | `get_gmail_messages_content_batch` | | Read a thread | `get_gmail_thread_content` | | Read multiple threads | `get_gmail_threads_content_batch` | | Send email (new or reply) | `send_gmail_message` | | Create draft | `draft_gmail_message` | | Download attachment | `get_gmail_attachment_content` | | Add/remove labels (one) | `modify_gmail_message_labels` | | Add/remove labels (batch) | `batch_modify_gmail_message_labels` | | Manage labels | `manage_gmail_label` | | List labels | `list_gmail_labels` | | Manage filters | `manage_gmail_filter` | | List filters | `list_gmail_filters` |

For parameters: [references/gmail.md](references/gmail.md)

Google Drive

| Task | Tool | |------|------| | Search files/folders | `search_drive_files` | | List items in folder | `list_drive_items` | | Read file content | `get_drive_file_content` | | Download file | `get_drive_file_download_url` | | Create file | `create_drive_file` | | Create folder | `create_drive_folder` | | Copy file | `copy_drive_file` | | Update file metadata | `update_drive_file` | | Share / set permissions | `set_drive_file_permissions` | | Manage access (add/remove) | `manage_drive_access` | | Check permissions | `get_drive_file_permissions` | | Get shareable link | `get_drive_shareable_link` | | Check public access | `check_drive_file_public_access` | | Import file to Google Doc | `import_to_google_doc` |

For parameters: [references/drive.md](references/drive.md)

Google Calendar

| Task | Tool | |------|------| | List calendars | `list_calendars` | | Get events | `get_events` | | Create/update/delete event | `manage_event` | | Check availability | `query_freebusy` |

For parameters: [references/calendar.md](references/calendar.md)

Google Docs

| Task | Tool | |------|------| | Read doc as Markdown | `get_doc_as_markdown` | | Read doc content (raw) | `get_doc_content` | | Create new doc | `create_doc` | | Modify text / apply styles | `modify_doc_text` | | Insert elements (tables, lists, breaks) | `insert_doc_elements` | | Insert image | `insert_doc_image` | | Create table with data | `create_table_with_data` | | Update paragraph styles | `update_paragraph_style` | | Find and replace | `find_and_replace_doc` | | Inspect structure | `inspect_doc_structure` | | Batch update (multiple ops) | `batch_update_doc` | | Headers/footers | `update_doc_headers_footers` | | Manage tabs | `manage_doc_tab` | | Export to PDF | `export_doc_to_pdf` | | List docs in folder | `list_docs_in_folder` | | Search docs | `search_docs` | | Comments | `manage_document_comment` / `list_document_comments` | | Debug table structure | `debug_table_structure` |

For parameters: [references/docs.md](references/docs.md)

Google Sheets

| Task | Tool | |------|------| | Read cell values | `read_sheet_values` | | Write/append/clear values | `modify_sheet_values` | | Format cells | `format_sheet_range` | | Conditional formatting | `manage_conditional_formatting` | | Get spreadsheet info | `get_spreadsheet_info`