managing-google-workspace - Claude MCP Skill

# 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`:

```bash
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:

```json
{
  "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` |
| 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 | `create_calendar` |
| Get events | `get_events` |
| Create/update/delete event | `manage_event` |
| Out of office (auto-decline) | `manage_out_of_office` |
| Focus time (auto-decline, DND) | `manage_focus_time` |
| 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` |
| Read plain text with link/chip targets and document segments | `get_doc_content(preserve_context=True)` |
| Create new doc | `create_doc` |
| Modify text / apply styles (by index or by `heading`) | `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` |
| Insert smart chips | `modify_sheet_values` (`chips`) |
| Format cells | `format_sheet_range` |
| Conditional formatting | `manage_conditional_formatting` |
| Get spreadsheet info | `get_spreadsheet_info` |
| Create spreadsheet | `create_spreadsheet` |
| Create sheet (tab) | `create_sheet` |
| Rename/delete/hide/reorder/style tab | `manage_sheet_tab` |
| Resize/freeze/hide/insert/delete rows and columns | `resize_sheet_dimensions` |
| Move rows between sheets | `move_sheet_rows` |
| List structured tables | `list_sheet_tables` |
| Append rows to structured table | `append_table_rows` |
| Manage named ranges | `manage_named_range` |
| List spreadsheets | `list_spreadsheets` |
| Comments | `manage_spreadsheet_comment` / `list_spreadsheet_comments` |

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

### Google Slides

| Task | Tool |
|------|------|
| Get presentation | `get_presentation` |
| Get specific slide | `get_page` |
| Look at a slide (render to image) | `render_page_to_image` |
| Create presentation | `create_presentation` |
| Batch update | `batch_update_presentation` |
| Speaker notes | `get_presentation` (`include_speaker_notes`) + `batch_update_presentation` |
| Comments | `manage_presentation_comment` / `list_presentation_comments` |

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

### Google Forms

| Task | Tool |
|------|------|
| Get form | `get_form` |
| Create form | `create_form` |
| Batch update form | `batch_update_form` |
| List responses | `list_form_responses` |
| Get one response | `get_form_response` |
| Publish settings | `set_publish_settings` |

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

### Google Tasks

| Task | Tool |
|------|------|
| List task lists | `list_task_lists` |
| Get task list | `get_task_list` |
| Manage task list (CRUD) | `manage_task_list` |
| List tasks | `list_tasks` |
| Get task | `get_task` |
| Manage task (CRUD/move) | `manage_task` |

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

### Google Contacts

| Task | Tool |
|------|------|
| Search contacts | `search_contacts` |
| Get contact | `get_contact` |
| Manage contact (CRUD) | `manage_contact` |
| Batch manage contacts | `manage_contacts_batch` |
| List contact groups | `list_contact_groups` |
| Get contact group | `get_contact_group` |
| Manage contact group | `manage_contact_group` |
| List all contacts | `list_contacts` |

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

### Google Chat

| Task | Tool |
|------|------|
| List spaces | `list_spaces` |
| Get messages | `get_messages` |
| Search messages | `search_messages` |
| Send message | `send_message` |
| Edit a message already sent | `send_message` (`message_name`) |
| React to message | `create_reaction` |
| Download attachment | `download_chat_attachment` |

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

### Google Apps Script

| Task | Tool |
|------|------|
| Projects/files (list/get) | `get_script_project` (`action`) |
| Projects (create/delete) | `manage_script_project` (`action`) |
| File content (update) | `manage_script_content` (`action="update"`) |
| Run function | `run_script_function` |
| Generate trigger code | `generate_trigger_code` |
| Deployments (list) | `list_script_deployments` |
| Deployments (create/update/delete) | `manage_deployment` (`action`) |
| Versions (list/get) | `get_script_version` (`action`) |
| Versions (create) | `manage_script_version` (`action="create"`) |
| Execution metrics / process history | `get_script_activity` (`action="metrics"` / `"processes"`) |
| Current user's triggers (list/delete) | `manage_script_trigger` (`action`) |

For parameters: [references/apps-script.md](references/apps-script.md)

### Google Custom Search

| Task | Tool |
|------|------|
| Web search | `search_custom` |
| Get search engine info | `get_search_engine_info` |

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

### Auth

| Task | Tool |
|------|------|
| Start OAuth flow | `start_google_auth` |

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. For parameters: [references/server-options.md](references/server-options.md#start_google_auth)

## 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**: The reference files document every parameter of every tool. In CLI mode, `workspace-cli list` shows which tools the running server exposes.