{ "markdown": "# google-workspace-mcp\n\n\n\n\n

\n \"License\"\n \"GitHub\n \"Last\n \"Open\n \"PyPI\n \"PyPI\n \"Built\n

\n\n\n\nMulti-account, token-efficient MCP for **Gmail + Calendar + Drive + Docs + Sheets**.\nBuilt because the official Claude connector supports one account and returns full\nmessage/file bodies by default.\n\n## Why this exists\n\n- **Multi-account**: OAuth multiple mailboxes (work + personal + co-founder). Every\n tool takes an `account` email; aliases are handled via Send-As identities.\n- **Token-efficient**: Search/list returns compact shapes (`{id, from, subject,\n snippet, ...}` for mail, `{id, name, mime, modified, size, ...}` for Drive).\n Bodies and file content are opt-in.\n- **Keyring-backed**: Refresh tokens live in the OS credential store — Keychain\n on macOS, Credential Manager on Windows, Secret Service on Linux — not in\n plaintext files. No tokens in the vault, no tokens in any repo.\n- **macOS, Windows and Linux**: one installer per platform, same connector.\n\n## Tools (v2, 63 tools)\n\n### Account management (3)\n- `gws_account_add` — browser OAuth flow, adds a new authorized mailbox\n- `gws_account_list` — list authorized accounts + default\n- `gws_account_remove` — remove local credential (doesn't revoke Google-side)\n\n### Gmail (12)\n- `gmail_search` — search with Gmail operators. Compact response.\n- `gmail_read` — read one message or full thread. Bodies opt-in.\n- `gmail_send` — send mail, optional `from_alias` for Send-As identities\n- `gmail_draft` — create a draft\n- `gmail_reply` — reply (preserves thread + headers), optional reply_all\n- `gmail_labels_list` — list all labels\n- `gmail_label_apply` — batch add/remove labels\n- `gmail_archive` — batch archive (remove INBOX)\n- `gmail_trash` — batch move to trash\n- `gmail_sendas_list` — list Send-As identities on this mailbox\n- `gmail_attachments_list` — list a message's attachments (filename, mime type, size)\n- `gmail_attachment_save` — download one attachment to a local file, path returned for direct reading\n\n### Calendar (7)\n- `cal_list_calendars` — list all calendars\n- `cal_list_events` — list upcoming events (compact by default, `verbose=True` for full)\n- `cal_create_event` — create event, optional Google Meet link\n- `cal_update_event` — partial-update fields\n- `cal_delete_event` — delete\n- `cal_freebusy` — check busy windows for scheduling\n- `cal_respond` — accept/decline/tentative\n\n### Drive (18)\n- `drive_search` — free-text or raw Drive q-syntax. Metadata-only response.\n- `drive_read_file` — metadata by default; `include_content=True` for body\n- `drive_list_folder` — direct children of a folder (`'root'` for My Drive)\n- `drive_create_folder` — create a folder under an optional parent\n- `drive_upload` — upload a local file, optional `convert_to_google`\n- `drive_move` — change parent folder\n- `drive_rename` — rename a file or folder\n- `drive_share` — grant reader/commenter/writer/etc. access by email\n- `drive_trash` — soft delete (recoverable)\n- `drive_untrash` — restore from Trash\n- `drive_permission_list` — list everyone with access to a file\n- `drive_permission_update` — change a grantee's role\n- `drive_permission_delete` — revoke a permission\n- `drive_shared_drives_list` — list shared drives this account accesses\n- `drive_comments_list` — list comments on any Drive file (Doc/Sheet/Slide/upload)\n- `drive_comment_add` — add a comment, optional anchor\n- `drive_comment_reply` — reply to a comment\n- `drive_comment_resolve` — mark a comment resolved\n\n### Docs (9)\n- `docs_create` — new Doc, optional initial body and parent folder\n- `docs_read` — flat text by default; `structured=True` for full Docs API tree\n- `docs_append` — append text to end of body\n- `docs_insert_at` — insert text at a specific index\n- `docs_replace_text` — find-and-replace, returns count replaced\n- `docs_export` — export to markdown / pdf / docx / rtf / plain\n- `docs_suggestions_list` — list pending tracked-change suggestions\n- `docs_suggestions_accept_all` — accept all suggestions (rewrites Doc)\n- `docs_suggestions_reject_all` — reject all suggestions (rewrites Doc)\n\n### Sheets (14)\n- `sheets_create` — new workbook, optional parent folder\n- `sheets_list_sheets` — list tabs with row/col dimensions\n- `sheets_add_sheet` — add a new tab to an existing workbook\n- `sheets_read_range` — read A1 range. `FORMULA` / `UNFORMATTED_VALUE` options.\n- `sheets_write_range` — overwrite a range. `USER_ENTERED` parses formulas.\n- `sheets_append` — append rows below existing data\n- `sheets_clear_range` — clear values (formatting preserved)\n- `sheets_batch_read` — multi-range read in one API call\n- `sheets_batch_write` — multi-range write in one API call\n- `sheets_named_ranges_list` — list named ranges in a workbook\n- `sheets_named_range_add` — create a named range\n- `sheets_named_range_delete` — delete a named range\n- `sheets_conditional_format_add` — add a conditional formatting rule\n- `sheets_data_validation_add` — set dropdown / number / email / URL validation\n\n## Install\n\n**Fastest path — one script, no manual wiring.**\n\nmacOS and Linux:\n\n```bash\ngit clone https://github.com/adelaidasofia/google-workspace-mcp.git\nbash google-workspace-mcp/install.sh\n```\n\nWindows (PowerShell):\n\n```powershell\ngit clone https://github.com/adelaidasofia/google-workspace-mcp.git\npowershell -ExecutionPolicy Bypass -File .\\google-workspace-mcp\\install.ps1\n```\n\nThe installer creates an isolated venv, installs dependencies, takes your\nGoogle OAuth client (either interactively or via `GWS_CLIENT_ID` /\n`GWS_CLIENT_SECRET` in the environment), and registers the server with\nClaude Code. Safe to re-run. You still need a Google OAuth client first —\nsee [SETUP.md](SETUP.md) for the ~45 min one-time GCP setup. Then run\n`gws_account_add` from Claude Code to authorize your first mailbox.\n\nBoth need Python 3.10 or newer and will find one you already have.\n\n- **macOS / Linux** try `python3` first, then `python3.14` down to\n `python3.10`, so a Homebrew Python still counts when `python3` resolves to\n macOS's older system one.\n- **Windows** tries `py -3` (the Python launcher) first, then `python`,\n `python3` and the versioned names. Every candidate has to run and report its\n own version before it counts, which is what keeps the Microsoft Store\n placeholder in `%LOCALAPPDATA%\\Microsoft\\WindowsApps` from being picked: it\n is a real `python.exe` on `PATH` that only opens the Store.\n\nIf yours lives somewhere no search would guess (pyenv, conda, a private\nprefix), name it:\n\n```bash\nGWS_PYTHON=/full/path/to/python3 bash google-workspace-mcp/install.sh\n```\n\n```powershell\n$env:GWS_PYTHON = 'C:\\full\\path\\to\\python.exe'\npowershell -ExecutionPolicy Bypass -File .\\google-workspace-mcp\\install.ps1\n```\n\n
\nWindows notes\n\n**`-ExecutionPolicy Bypass` is in the command on purpose.** Windows blocks\ndownloaded scripts by default; this applies the exception to this one run\nwithout changing the machine's policy.\n\n**Run it from PowerShell, not Git Bash.** `install.sh` detects Git Bash / MSYS\nand stops there with a pointer to `install.ps1`, rather than registering a\nPOSIX venv path that a native Claude Code cannot launch. WSL is real Linux and\nkeeps using `install.sh`.\n\n**Time zone.** The connector reads the machine's IANA zone so that \"3pm\" in a\n`cal_*` call means 3pm where you are. Windows names its zones its own way\n(`SA Western Standard Time`), so this goes through `tzlocal`, which the\ninstaller pulls in. Set `GWS_TIME_ZONE=America/Bogota` to override.\n\n
\n\n
\nPlugin marketplace install\n\nOpen Claude Code, paste:\n\n /plugin marketplace add adelaidasofia/google-workspace-mcp\n /plugin install google-workspace-mcp@google-workspace-mcp\n\nYou still need to complete the one-time GCP setup in [SETUP.md](SETUP.md)\n(~45 min for v1, ~5 min incremental for v2 Drive/Docs/Sheets) so the\nserver has a `client_secret.json` to OAuth against. Run `gws_account_add`\nfrom Claude Code to authorize your first mailbox.\n\n**On Windows, run `install.ps1` afterwards.** The plugin's `.mcp.json` launches\nthe server with `python3`, and a plugin manifest has no way to say \"except on\nWindows, use this instead\". On Windows `python3` is either absent or the\nMicrosoft Store placeholder, so the connector is registered and never starts.\n`install.ps1` re-registers it against an absolute interpreter path, which is\nunambiguous on every platform.\n\n
\n\n
\nLegacy install (manual .mcp.json wiring)\n\nSee [SETUP.md](SETUP.md) for the one-time GCP setup (~45 min for v1, ~5 min\nincremental to enable Drive/Docs/Sheets for v2).\n\nAfter setup:\n```bash\npip3 install --break-system-packages -r requirements.txt\n```\n\n### Register with Claude Code\n\nAdd to your project's `.mcp.json` (or `~/.claude.json` for global access):\n```json\n\"google-workspace\": {\n \"type\": \"stdio\",\n \"command\": \"python3\",\n \"args\": [\"/path/to/google-workspace-mcp/server.py\"]\n}\n```\n\nOn Windows, give the full path to a real interpreter rather than a bare name —\n`python3` there is usually the Microsoft Store placeholder, which resolves fine\nand never runs Python:\n```json\n\"google-workspace\": {\n \"type\": \"stdio\",\n \"command\": \"C:\\\\Users\\\\you\\\\google-workspace-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\"C:\\\\Users\\\\you\\\\google-workspace-mcp\\\\server.py\"]\n}\n```\n\n
\n\n## Upgrading from v1 → v2\n\nv2 adds Drive + Docs + Sheets scopes. **Each authorized account must re-OAuth\nonce** so Google grants the new scopes. See SETUP.md step 6b.\n\n## Roadmap\n\n- **v3**: Gmail filters, vacation responder, push notifications (Gmail Watch),\n Calendar ACL/delegation, Slides, Forms, Tasks\n- **v4**: Batch requests across services, Drive revisions\n\n## Related MCPs\n\nSame author, same architecture pattern (FastMCP, draft+confirm on writes where applicable, vault auto-export, MIT):\n\n- [slack-mcp](https://github.com/adelaidasofia/slack-mcp) — multi-workspace Slack\n- [imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) — macOS iMessage\n- [whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) — WhatsApp via whatsmeow\n- [apollo-mcp](https://github.com/adelaidasofia/apollo-mcp) — Apollo.io CRM + sequences\n- [substack-mcp](https://github.com/adelaidasofia/substack-mcp) — Substack writing + analytics\n- [luma-mcp](https://github.com/adelaidasofia/luma-mcp) — lu.ma events\n- [parse-mcp](https://github.com/adelaidasofia/parse-mcp) — markitdown / Docling / LlamaParse router\n- [rescuetime-mcp](https://github.com/adelaidasofia/rescuetime-mcp) — RescueTime productivity data\n- [graph-query-mcp](https://github.com/adelaidasofia/graph-query-mcp) — vault knowledge graph queries\n- [graph-autotagger-mcp](https://github.com/adelaidasofia/graph-autotagger-mcp) — wikilink suggestions from the graph\n- [investor-relations-mcp](https://github.com/adelaidasofia/investor-relations-mcp) — seed-raise pipeline tracker\n- [vault-sync-mcp](https://github.com/adelaidasofia/vault-sync-mcp) — bidirectional vault sync\n\n\n## Telemetry\n\nThis plugin sends a single anonymous install signal to `myceliumai.co` the first time it loads in a Claude Code session on a given machine.\n\n**What is sent:**\n- Plugin name (e.g. `slack-mcp`)\n- Plugin version (e.g. `0.1.0`)\n\n**What is NOT sent:**\n- No user identifiers, names, emails, tokens, or API keys\n- No file paths, message content, or anything from your work\n- No IP address is stored after dedup processing\n\n**Why:** Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.\n\n**Opt out:** Set the environment variable `MYCELIUM_NO_PING=1` before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at `~/.mycelium/onboarded-` — delete it if you want to reset state.\n\n## License\n\nMIT\n\n---\n\nBuilt by [Mycelium AI](https://myceliumai.co). Full install or team version at [diazroa.com](https://diazroa.com).\n", "bytes": 13190, "sha": "9b9a08ad9300f5675178585a1a38e09ed065ba254ab50087eff92ef467d4024f", "repo_slug": "adelaidasofia/google-workspace-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_adelaidasofia_google_workspace_mcp_googl_487b3463/readme" }