google_workspace_mcp

--- **See it in action:** --- ## What It Does Workspace MCP connects AI assistants to all twelve major Google Workspace services - 120+ tools behind a single MCP server, with OAuth 2.1 multi-user auth, three progressive tool tiers, read-only mode, a full CLI, and stateless container deployment. It runs locally over stdio for legacy clients and remotely over streamable HTTP with full implementation of the latest MCP spec. The README covers just enough to get you running, with extensive documentation on the website: | Where to go | What you'll find | |:---|:---| | **[Quick Start](https://workspacemcp.com/quick-start?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-quickstart)** | Google Cloud setup, credentials, and client connection with screenshots | | **[Full Documentation](https://workspacemcp.com/docs?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-docs)** | Every tool, parameter, and auth mode | | **[Advanced Deployment](https://workspacemcp.com/docs/deployment?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-deployment)** | Reverse proxy & nginx config, origin validation, credential store backends (GCS/CMEK), [trusted-gateway identity](https://workspacemcp.com/docs/deployment/gateway-identity?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-gateway-identity), and the complete environment variable reference | | **[Client Setup Guides](https://workspacemcp.com/guides?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-guides)** | Claude Desktop/web Connectors, ChatGPT Developer Mode, and more | | **[FAQ & Troubleshooting](https://workspacemcp.com/welcome/faq?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=nav-faq)** | OAuth errors, redirect URIs, Google Chat setup, client quirks | ## Security & Compliance

**For Security Teams** By default, this server sends no data anywhere except Google's APIs, on behalf of the authenticated user, using your own OAuth client credentials. There is no usage reporting, analytics, license server, or SaaS dependency outside optional OTel support for your own usage. - **Fully open source** — every line is auditable in this repo - **Your OAuth client, your GCP project** — credentials never leave your environment & you control scopes - **You control the network** — deploy behind your reverse proxy, in your VPC, on your own terms - **Stateless mode** — zero disk writes for locked-down container environments - **Sensitive path blocking** — local file reads default to the managed attachment directory, and `validate_file_path()` still blocks `.env*` files plus common home-directory credential stores such as `~/.ssh/` and `~/.aws/` even if `ALLOWED_FILE_DIRS` is broadened Full dependency tree in `pyproject.toml`, pinned in `uv.lock`.

**For Legal & Procurement** This project is [MIT licensed](LICENSE) — not "open core," not "source available," not "free with a CLA." There is no dual licensing, no commercial tier gating features, and no contributor license agreement. - **Use commercially without restriction** — build products, sell services, deploy internally - **Fork, embed, redistribute** — MIT requires only attribution - **No CLA** — contributions remain under MIT - **No built-in telemetry to disclose** — optional tracing is off unless you configure it - **No network effects** — the server never contacts any endpoint you didn't configure - **Standard dependency licenses** — MIT, Apache 2.0, and BSD throughout the dependency chain; no copyleft, no AGPL

## Services

Gmail 15 tools - search, send, draft, labels, filters, attachments	Drive 16 tools - search, create, share, import Office files	Calendar 7 tools - events, free/busy, Out of Office, Focus Time	Docs 19 tools - edit, style, tables, tabs, comments, export
Sheets 14 tools - ranges, tables, formatting, conditional rules	️ Slides 7 tools - create, batch update, thumbnails, comments	Forms 6 tools - build forms, publish, read responses	✅ Tasks 6 tools - tasks & lists with hierarchy
Contacts 8 tools - people, groups, batch operations	Chat 6 tools - spaces, messages, search, reactions	Custom Search 2 tools - programmable web search	⚡ Apps Script 15 tools - write, deploy, run & debug scripts

Each page lists every tool with its tier, parameters, required scopes, and example prompts. The [complete reference](https://workspacemcp.com/docs?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=services-docs-all) covers all twelve in one place. > **Google Chat** needs a one-time Chat app configuration and a Workspace account - see the [Chat setup FAQ](https://workspacemcp.com/welcome/faq?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=services-chat-faq). ## Quick Start > Set credentials → pick a launch command → connect your client. Full walkthrough with screenshots: **[workspacemcp.com/quick-start](https://workspacemcp.com/quick-start?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=quickstart-hero)** You'll need an OAuth client from [Google Cloud Console](https://console.cloud.google.com/) with the APIs enabled for the services you plan to use - the [quick start guide](https://workspacemcp.com/quick-start?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=quickstart-inline) walks through it in about five minutes.

**Confidential Client** ```bash # 1. Credentials export GOOGLE_OAUTH_CLIENT_ID="..." export GOOGLE_OAUTH_CLIENT_SECRET="..." # 2. Launch - pick a tier uvx workspace-mcp --tool-tier core # essential tools uvx workspace-mcp --tool-tier extended # core + management ops uvx workspace-mcp --tool-tier complete # everything # Or cherry-pick services uvx workspace-mcp --tools gmail drive calendar ```

**OAuth 2.1 (PKCE)** ``` … ```

**Tool tiers** keep context windows lean: `core` is the essential set, `extended` adds management operations, `complete` loads everything. Combine with `--tools ...`, `--read-only`, or per-service `--permissions`, and subtract individual tools with `--disabled-tools ...` - details in the [server modes docs](https://workspacemcp.com/docs?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=tiers-server-modes#server-modes). ## Connect Your Client **Claude Desktop, web & mobile** - run the server in HTTP mode and add it as a **Connector** (Settings → Connectors → Add custom connector). This is the recommended path; the [Connector guide](https://workspacemcp.com/guides/claude-connectors?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=clients-connectors) has step-by-step screenshots. Legacy stdio configuration remains available for clients without Connector support - see the [FAQ](https://workspacemcp.com/welcome/faq?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=clients-connectors-faq). **Claude Code** ```bash # Start the server in HTTP mode, then: claude mcp add --transport http workspace-mcp http://localhost:8000/mcp # Optional: install the bundled skill for better Workspace tool routing ln -s "$(pwd)/skills/managing-google-workspace" ~/.claude/skills/managing-google-workspace ``` **ChatGPT** - connect via Developer Mode with the [ChatGPT guide](https://workspacemcp.com/guides/chatgpt-developer-mode?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=clients-chatgpt). **VS Code, LM Studio, Open WebUI, and everything else** - any MCP client works over streamable HTTP (recommended) or stdio. Client-specific walkthroughs live in the [guides](https://workspacemcp.com/guides?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=clients-guides) and [FAQ](https://workspacemcp.com/welcome/faq?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=clients-guides-faq). ## CLI `workspace-cli` lists and calls tools against a running server with encrypted, disk-backed OAuth token caching - authenticate once, script forever: ```bash uv run workspace-cli list uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5 ``` Install globally with `uv tool install .` from this repo. ⚠️ Don't use `uvx workspace-cli` - an abandoned PyPI package squats that name. ## Deployment & Advanced Configuration Everything you need to run this in production lives in two places. The [documentation](https://workspacemcp.com/docs?utm_source=github.com&utm_medium=referral&utm_campaign=readme&utm_content=deploy-docs) covers auth modes and server configuration: - *