taylorwilsdon 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_authto 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 byWORKSPACE_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
actionparameter 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 |
For parameters: 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
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
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 |
| Create spreadsheet | create_spreadsheet |
| Create sheet (tab) | create_sheet |
| Move rows between sheets | move_sheet_rows |
| 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 |
| Get slide thumbnail | get_page_thumbnail |
| 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 with message_name |
| React to message | create_reaction |
| Download attachment | download_chat_attachment |
For parameters: references/chat.md
Google Apps Script
| Task | Tool |
|---|---|
| List projects | list_script_projects |
| Get project | get_script_project |
| Create project | create_script_project |
| Delete project | delete_script_project |
| Get file content | get_script_content |
| Update file content | update_script_content |
| Run function | run_script_function |
| Generate trigger code | generate_trigger_code |
| Manage deployments | manage_deployment / list_deployments |
| Versions | create_version / get_version / list_versions |
| Execution metrics | get_script_metrics |
| Process history | list_script_processes |
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 |
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
search_gmail_messages-- find the emailget_gmail_message_content-- read it (getmessage_idandthread_id)send_gmail_message-- reply usingthread_id; omit reply headers to target the latest non-draft, non-trash message with an RFCMessage-ID
Find and share a file
search_drive_files-- find the filemanage_drive_access-- share itget_drive_shareable_link-- get the link
Read and update a spreadsheet
get_spreadsheet_info-- get sheet namesread_sheet_values-- read current datamodify_sheet_values-- write updated dataread_sheet_values-- verify the update
Create a formatted document
create_doc-- create the docmodify_doc_text-- add text with formattinginsert_doc_elements-- add tables, lists, page breaksupdate_paragraph_style-- apply heading stylesget_doc_as_markdown-- verify the result
Process email attachments
search_gmail_messages-- find the emailget_gmail_message_content-- get attachment metadataget_gmail_attachment_content-- download the attachment
Edit a Google Doc
get_doc_as_markdown-- read current contentinspect_doc_structure-- find insertion points and indicesmodify_doc_text/insert_doc_elements-- make changesget_doc_as_markdown-- verify the result
Tips
- Check parameters: In CLI mode, run
uvx workspace-mcp --cli <tool> --helpfor any unfamiliar tool.