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.
• Keyring-backed: Refresh tokens live in the OS credential store — Keychain on macOS, Credential Manager on Windows, Secret Service on Linux — not in plaintext files. No tokens in the vault, no tokens in any repo.
• macOS, Windows and Linux: one installer per platform, same connector.

Tools (v2, 63 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 (12)

• 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
• gmail_attachments_list — list a message's attachments (filename, mime type, size)
• gmail_attachment_save — download one attachment to a local file, path returned for direct reading

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

Fastest path — one script, no manual wiring.

macOS and Linux:

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
bash google-workspace-mcp/install.sh

Windows (PowerShell):

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

The installer creates an isolated venv, installs dependencies, takes your Google OAuth client (either interactively or via GWS_CLIENT_ID / GWS_CLIENT_SECRET in the environment), and registers the server with Claude Code. Safe to re-run. You still need a Google OAuth client first — see SETUP.md for the ~45 min one-time GCP setup. Then run gws_account_add from Claude Code to authorize your first mailbox.

Both need Python 3.10 or newer and will find one you already have.

• macOS / Linux try python3 first, then python3.14 down to python3.10, so a Homebrew Python still counts when python3 resolves to macOS's older system one.
• Windows tries py -3 (the Python launcher) first, then python, python3 and the versioned names. Every candidate has to run and report its own version before it counts, which is what keeps the Microsoft Store placeholder in %LOCALAPPDATA%\Microsoft\WindowsApps from being picked: it is a real python.exe on PATH that only opens the Store.

If yours lives somewhere no search would guess (pyenv, conda, a private prefix), name it:

GWS_PYTHON=/full/path/to/python3 bash google-workspace-mcp/install.sh

$env:GWS_PYTHON = 'C:\full\path\to\python.exe'
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

/plugin marketplace add adelaidasofia/google-workspace-mcp
/plugin install google-workspace-mcp@google-workspace-mcp

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