/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 the workspace-cli client. Provides tool routing, workflows, and parameter guidance for every tool.
  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(workspace-cli *), Bash(uv run workspace-cli *)
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, call a running server via `workspace-cli`:

workspace-cli list
workspace-cli call <tool_name> key=value ...

• Pass `user_google_email=USER_EMAIL` only when the tool schema requires it (legacy OAuth 2.0 without `USER_GOOGLE_EMAIL` set). Omit it for OAuth 2.1 and trusted-gateway servers, which take it from the verified identity.
• Arguments are `key=value` pairs; values are parsed as JSON when possible, so pass lists and objects as JSON (e.g. `label_ids='["INBOX"]'`).
• The server must be reachable over HTTP. The default URL is `http://localhost:8000/mcp` (a server started with `--transport streamable-http`); override it with `--url` before the subcommand (`workspace-cli --url <url> call ...`) or `WORKSPACE_MCP_URL`. Plugin users on stdio can set `WORKSPACE_MCP_HTTP_PORT` to expose a loopback sidecar at `http://127.0.0.1:<port>/mcp`.
• If `workspace-cli` is not on PATH, run `uv run workspace-cli` from a checkout of this repo. Installing it permanently (`uv tool install .` in that checkout) is a manual setup step for the user. Never use `uvx workspace-cli`: an unrelated, abandoned PyPI package squats that name.

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, or page a long body | `get_gmail_message_content` (`page_offset`, `page_size`, `expected_sha256`) | | 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` | | Create shortcut | `create_drive_file` (`shortcut_target_id`) | | 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` | | Import spreadsheet (XLSX, CSV, ...) to Google Sheets | `import_to_google_sheets` | | Import presentation (PPTX, ...) to Google Slides | `import_to_google_slides` |

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

Google Calendar

| Task | Tool | |------|------| | List calendars | `list_calendars` | | Create secondary calendar / share calendar, list, update or remove access | `manage_calendar` | | Get events | `get_