managing-google-workspace

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:

• 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

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

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

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

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

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

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

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

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

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

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

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

Google Custom Search

Task	Tool
Web search	search_custom
Get search engine info	get_search_engine_info

For parameters: 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

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.