google-workspace-mcp

Multi-account, token-efficient MCP for Gmail + Calendar + Drive + Docs + Sheets. Built because the official Claude connector supports one account and returns full message/file bodies by default.

Why this exists

• Multi-account: OAuth multiple mailboxes (work + personal + co-founder). Every tool takes an account email; aliases are handled via Send-As identities.
• Token-efficient: Search/list returns compact shapes ({id, from, subject, snippet, ...} for mail, {id, name, mime, modified, size, ...} for Drive). Bodies and file content are opt-in.
• Keychain-backed: Refresh tokens live in the macOS Keychain, not plaintext files. No tokens in the vault, no tokens in any repo.

Tools (v2, 61 tools)

Account management (3)

• gws_account_add — browser OAuth flow, adds a new authorized mailbox
• gws_account_list — list authorized accounts + default
• gws_account_remove — remove local credential (doesn't revoke Google-side)

Gmail (10)

• gmail_search — search with Gmail operators. Compact response.
• gmail_read — read one message or full thread. Bodies opt-in.
• gmail_send — send mail, optional from_alias for Send-As identities
• gmail_draft — create a draft
• gmail_reply — reply (preserves thread + headers), optional reply_all
• gmail_labels_list — list all labels
• gmail_label_apply — batch add/remove labels
• gmail_archive — batch archive (remove INBOX)
• gmail_trash — batch move to trash
• gmail_sendas_list — list Send-As identities on this mailbox

Calendar (7)

• cal_list_calendars — list all calendars
• cal_list_events — list upcoming events (compact by default, verbose=True for full)
• cal_create_event — create event, optional Google Meet link
• cal_update_event — partial-update fields
• cal_delete_event — delete
• cal_freebusy — check busy windows for scheduling
• cal_respond — accept/decline/tentative

Drive (18)

• drive_search — free-text or raw Drive q-syntax. Metadata-only response.
• drive_read_file — metadata by default; include_content=True for body
• drive_list_folder — direct children of a folder ('root' for My Drive)
• drive_create_folder — create a folder under an optional parent
• drive_upload — upload a local file, optional convert_to_google
• drive_move — change parent folder
• drive_rename — rename a file or folder
• drive_share — grant reader/commenter/writer/etc. access by email
• drive_trash — soft delete (recoverable)
• drive_untrash — restore from Trash
• drive_permission_list — list everyone with access to a file
• drive_permission_update — change a grantee's role
• drive_permission_delete — revoke a permission
• drive_shared_drives_list — list shared drives this account accesses
• drive_comments_list — list comments on any Drive file (Doc/Sheet/Slide/upload)
• drive_comment_add — add a comment, optional anchor
• drive_comment_reply — reply to a comment
• drive_comment_resolve — mark a comment resolved

Docs (9)

• docs_create — new Doc, optional initial body and parent folder
• docs_read — flat text by default; structured=True for full Docs API tree
• docs_append — append text to end of body
• docs_insert_at — insert text at a specific index
• docs_replace_text — find-and-replace, returns count replaced
• docs_export — export to markdown / pdf / docx / rtf / plain
• docs_suggestions_list — list pending tracked-change suggestions
• docs_suggestions_accept_all — accept all suggestions (rewrites Doc)
• docs_suggestions_reject_all — reject all suggestions (rewrites Doc)

Sheets (14)

• sheets_create — new workbook, optional parent folder
• sheets_list_sheets — list tabs with row/col dimensions
• sheets_add_sheet — add a new tab to an existing workbook
• sheets_read_range — read A1 range. FORMULA / UNFORMATTED_VALUE options.
• sheets_write_range — overwrite a range. USER_ENTERED parses formulas.
• sheets_append — append rows below existing data
• sheets_clear_range — clear values (formatting preserved)
• sheets_batch_read — multi-range read in one API call
• sheets_batch_write — multi-range write in one API call
• sheets_named_ranges_list — list named ranges in a workbook
• sheets_named_range_add — create a named range
• sheets_named_range_delete — delete a named range
• sheets_conditional_format_add — add a conditional formatting rule
• sheets_data_validation_add — set dropdown / number / email / URL validation

Install

See SETUP.md for the one-time GCP setup (~45 min for v1, ~5 min incremental to enable Drive/Docs/Sheets for v2).

After setup:

pip3 install --break-system-packages -r requirements.txt

Register with Claude Code

Add to your project's .mcp.json (or ~/.claude.json for global access):

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

Upgrading from v1 → v2

v2 adds Drive + Docs + Sheets scopes. Each authorized account must re-OAuth once so Google grants the new scopes. See SETUP.md step 6b.

Roadmap

• v3: Gmail filters, vacation responder, push notifications (Gmail Watch), Calendar ACL/delegation, Slides, Forms, Tasks
• v4: Batch requests across services, Drive revisions

License

MIT