Google Workspace MCP Server

Full natural language control over Google Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Contacts, and Chat through all MCP clients, AI assistants and developer tools. Includes a full featured CLI & Code Mode for use with tools like Claude Code and Codex!

The fastest, most feature-complete Google Workspace MCP server is in a class of it's own: it can do things that Google's own tooling and the built in integrations with Claude and ChatGPT can't come close to with multi-user support, rich fine-grained editing tools and the most extensive coverage of any Workspace AI integration in existence.

By leveraging native OAuth 2.1, stateless deployment capability and external auth server & gateway passthrough auth support, it's also the only Workspace MCP you can host for your whole organization centrally & securely! Supports all free Google accounts & Google Workspace plans with expanded app options like Chat & Spaces.

See it in action:

google_workspace_mcp.mp4

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	Google Cloud setup, credentials, and client connection with screenshots
Full Documentation	Every tool, parameter, and auth mode
Advanced Deployment	Reverse proxy & nginx config, origin validation, credential store backends (GCS/CMEK), trusted-gateway identity, and the complete environment variable reference
Client Setup Guides	Claude Desktop/web Connectors, ChatGPT Developer Mode, and more
FAQ & Troubleshooting	Enabling Google APIs, 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 —

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, slide images, 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 covers all twelve in one place.

💬 Google Chat needs a one-time Chat app configuration and a Workspace account - see the Chat setup FAQ.

Quick Start

Set credentials → pick a launch command → connect your client. Full walkthrough with screenshots: workspacemcp.com/quick-start

You'll need an OAuth client from Google Cloud Console in a project with the Google APIs enabled for the services you plan to use. The docs have one-click enable links for every API plus a single gcloud services enable command that covers them all, and the quick start guide walks through the whole setup in about five minutes.

Agentic OAuth clients: this server only calls Google's REST APIs, so your OAuth client does not need Google's "Use this client for an AI-powered agent" setting. If your organization wants agent traffic labeled for admin controls, create a separate client with that setting enabled; it can't be changed on an existing client after November 12, 2026.

Confidential Client

# 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)

# 1. Credentials - MCP clients connect with PKCE and no
#    secret, but Google still requires one server-side
export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."
#    Alternatively, point GOOGLE_CLIENT_SECRET_PATH at a client_secret.json
#    that contains the client id and secret (env vars take precedence).
export WORKSPACE_MCP_PORT=8000
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback"
export OAUTHLIB_INSECURE_TRANSPORT=1

# 2. Launch - OAuth 2.1 requires HTTP transport
uvx workspace-mcp --transport streamable-http --tool-tier core

Tool tiers keep context windows lean: core is the essential set, extended adds management operations, complete loads everything. Combine with --tools <service> ..., --read-only, or per-service --permissions, and subtract individual tools with --disabled-tools <name> ... - details in the server modes docs.

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 has step-by-step screenshots. Legacy stdio configuration remains available for clients without Connector support - see the FAQ.

Claude Code

# 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.

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 and FAQ.

CLI

workspace-cli lists and calls tools against a running server with encrypted, disk-backed OAuth token caching - authenticate once, script forever:

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 covers auth modes and server configuration:

OAuth 2.1 multi-user auth - bearer tokens, required for remote or shared HTTP endpoints
Stateless container mode - zero disk writes for locked-down deployments
OAuth proxy storage backends - memory, disk, or Valkey/Redis for distributed setups
External OAuth provider mode - bring your own auth server, validate bearer tokens only
Service accounts with domain-wide delegation - per-request user impersonation with an optional domain allowlist
Trusted-gateway identity - proxy-verified per-user isolation with Pomerium, Cloudflare Access, oauth2-proxy, or any JWKS-verifiable gateway
OpenTelemetry tracing - optional, off unless you configure an OTLP endpoint
Docker - docker build -t workspace-mcp . && docker run -p 8000:8000 workspace-mcp

The Advanced Deployment guide covers self-hosting specifics: reverse proxy setup with WORKSPACE_EXTERNAL_URL (including the nginx Origin: null consent workaround, the WORKSPACE_MCP_ALLOW_NULL_ORIGIN_CONSENT escape hatch, and the Referrer-Policy pitfall), origin validation and VS Code webview allowlisting, credential store backends (local directory or GCS with CMEK enforcement), and the complete environment variable reference.

Production tuning is all environment variables; the names below link to their reference entries.

Google API requests: WORKSPACE_MCP_GOOGLE_API_WORKERS, WORKSPACE_MCP_GOOGLE_API_TIMEOUT_SECONDS
External OAuth token validation: WORKSPACE_MCP_TOKEN_VALIDATION_WORKERS, WORKSPACE_MCP_TOKEN_VALIDATION_CACHE_TTL
Memory ceilings: WORKSPACE_MCP_MAX_FILE_BYTES, WORKSPACE_MCP_STATELESS_INLINE_MAX_BYTES, WORKSPACE_MCP_MAX_OFFICE_XML_BYTES
Text returned per call: get_drive_file_content returns long content a page at a time by default, so a long file does not fill the model's context. WORKSPACE_MCP_MAX_CONTENT_CHARS sets the page size (default 40000; 0 returns whole content by default). Each page ends with a note giving the offset to read on from. This is only the default: a client can always pass full_content=true to get the whole file in one call. Text being read page by page is kept in memory for ten minutes so later pages are not downloaded again, within WORKSPACE_MCP_PAGED_CONTENT_CACHE_BYTES per process (default 33554432, 32 MiB; 0 keeps nothing).
Sessions and health probes: WORKSPACE_MCP_SESSION_IDLE_TIMEOUT, WORKSPACE_MCP_READINESS_TIMEOUT_SECONDS
DNS-rebinding protection: WORKSPACE_MCP_ALLOWED_HOSTS, a comma-separated list of hostnames without ports (for example workspace-mcp,10.0.0.5). When set, requests whose Host is not loopback, listed, or the host of WORKSPACE_EXTERNAL_URL or an allowed origin get 403, so include every name clients and health probes use. Unset, any Host is accepted.
Hosted servers without access to the caller's disk: WORKSPACE_MCP_DISABLE_LOCAL_FILES With local files disabled, create_drive_file, update_drive_file and the import tools offer return_upload_url: the caller PUTs the bytes to the returned URL. If the file sits in a cloud-mirrored folder (Drive for desktop), copy it to a local directory first, since mirrored paths can stall mid-upload.
OAuth 2.1 token refresh and lifetimes: see .env.oauth21
OAuth 2.1 consent screen: WORKSPACE_MCP_OAUTH_PROXY_REQUIRE_CONSENT=remember shows the OAuth proxy's consent screen once per browser for each MCP client instead of on every authorization; cross-site navigations are still prompted. The default, always, prompts every time. Any other value fails startup.

For downloads, horizontally scaled or scale-to-zero HTTP deployments (Cloud Run, Kubernetes) can stage attachments in Google Cloud Storage instead of instance-local disk, whose /attachments/{id} URL may reach a different instance. Install the gcs extra and set WORKSPACE_MCP_FILES_GCS_BUCKET to a bucket name; objects are written under WORKSPACE_MCP_FILES_GCS_PREFIX (default attachments) and handed out as V4 signed URLs valid for one hour, which the client fetches straight from GCS. This also lets stateless mode return download URLs instead of inline files. stdio ignores the setting, since its client reads the local file path directly. The runtime service account needs object read and write access on the bucket — roles/storage.objectUser, or roles/storage.objectCreator plus roles/storage.objectViewer — and, without an exported private key, roles/iam.serviceAccountTokenCreator on itself so URLs can be signed through IAM. Read access is not optional: a signed URL carries the signer's authority, so without storage.objects.get the upload and the signing both succeed while the client's download fails with 403. Objects are not deleted by the server, so add a bucket lifecycle rule that removes them after a few hours.

Security Best Practices

By default this server sends no data anywhere except Google's APIs, using your own OAuth client credentials - no usage reporting, analytics, license server, or SaaS dependency. MIT licensed with no CLA, no dual licensing, and no copyleft in the dependency chain. The full security posture - scope minimization, sensitive-path blocking, stateless mode - is documented at workspacemcp.com.

A few things worth internalizing before you connect an LLM to your email:

Prompt injection is real. Emails, do

google_workspace_mcp

Install

What we checked

README

More in Plugins

Unity-MCP

linkedin-mcp-server

cli

Auto-claude-code-research-in-sleep