Control Google Workspace with Natural Language

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 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. Interested in a managed cloud instance? That can be arranged (starting at $5/mo).

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:

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

📧

📁

📅

📝

📊

🖼️

📋

✅

👤

💬

🔍

⚡

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.

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. Optional per-download payload ceiling for container deployments: set WORKSPACE_MCP_MAX_FILE_BYTES to a positive byte count (e.g. 5242880 for 5 MiB) to reject Drive / Gmail / Chat / Google Docs downloads that would otherwise be fully buffered in-process. Unset or 0 leaves the total size uncapped; uncapped Drive transfers still use 256 KiB transport chunks instead of the Google client's 100 MiB default. This is a file-size limit, not a process-RSS limit: leave headroom for parsing, base64/JSON representation, and concurrent tool calls. Invalid or negative values fail server startup instead of silently disabling the limit. Downloads streamed directly to disk are not subject to this in-memory payload ceiling.

Hosted deployments where the server cannot see the caller's disk can set WORKSPACE_MCP_DISABLE_LOCAL_FILES=true. Tools then stop advertising server-side file_path parameters and refuse local paths with guidance to pass a URL or inline content instead. Stateless mode implies this setting. It is off by default, including for streamable HTTP, because a server on localhost shares the client's filesystem.

On such a server uploads can bypass it entirely: create_drive_file, update_drive_file and the import_to_google_* tools accept return_upload_url=true, which opens a Google Drive resumable upload session and returns its pre-authorized URL. The client then PUTs the bytes straight to Google (no Authorization header), so large or binary files never pass through the MCP server or the model context. The two settings are two sides of one switch: return_upload_url is advertised only when WORKSPACE_MCP_DISABLE_LOCAL_FILES is set (or in stateless mode), and a server with local file access refuses it, since file_path is the route there.

Office files (.docx, .xlsx, .pptx) are ZIP archives, so the ceiling above bounds only their compressed size. Text extraction separately applies WORKSPACE_MCP_MAX_OFFICE_XML_BYTES (default 26214400, 25 MiB) as independent limits on expanded XML and extracted UTF-8 text. A file beyond either limit is reported as too large to extract. These limits bound input and output size, not process memory: the parsed XML tree measured roughly 14 to 30 times the XML size, so lower the value on small containers. 0 removes both limits; invalid or negative values fail server startup.

Advanced OAuth 2.1 deployments affected by concurrent client token refreshes can tune FastMCP's early-refresh threshold and client-facing access-token lifetime, and deployments that want to bound how long per-login records stay in the OAuth proxy storage backend can shorten the client-facing refresh-token lifetime. See .env.oauth21 for the bounded settings, recommended values, and security tradeoffs. The first two settings reduce how often the race occurs; they do not add a grace period to FastMCP's one-time-use refresh-token rotation.

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, docs, and events can contain hidden instructions. Only connect trusted data to an LLM, and be deliberate about which write tools you enable.
• Never commit .env, client_secret.json, or .credentials/ to source control.
• Local file reads are sandboxed to the managed attachment directory. Broaden with ALLOWED_FILE_DIRS only if you trust the client and its data sources; .env*, ~/.ssh/, ~/.aws/, and similar paths are always blocked.
• Production deployments should use HTTPS and OAuth 2.1.

Development

uv sync --group dev    # install deps
uv run ruff check .    # lint
uv run pytest          # test

Single-file service modules live in g<service>/, tools are registered with @server.tool decorators, and tiers are defined in core/tool_tiers.yaml. PRs welcome.